Function arguments are getting shuffled around

[spookey]

Hello,
currently I'm stuck, can you help me?

I have the following snippet of code:

template<typename T>
bool something(T* base, uint8_t (T::*member)(long));

If I run this through doxygen it gets parsed properly (I was looking into the xml files), but sphinx throws the following warning:

/bla/bla/bla/doc/index.rst:4: WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters and qualifiers
  Invalid definition: Expected identifier in nested name, got keyword: bool [error at 4]
    bool something(T * base, uint8_t(T::*)(long) member)
    ----^
If the function has a return type:
  Error in declarator or parameters and qualifiers
  If pointer to member declarator:
    Invalid definition: Expected '::' in pointer to member (function). [error at 14]
      bool something(T * base, uint8_t(T::*)(long) member)
      --------------^
  If declarator-id:
    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "m". [error at 45]
      bool something(T * base, uint8_t(T::*)(long) member)
      ---------------------------------------------^

This is quite annoying, as uint8_t (T::*member)(long) is something completely different than uint8_t(T::*)(long) member...

How can I prevent those warnings, and generate proper output? (the signature is also wrong in the rendered html)
Is breathe doing the shuffling here, or someone different?

I have set up some minimal example to showcase this issue, I'll will upload it here, if someone here asks for it.

Thanks.

[spookey]

Hello, anyone there?!?

I "solved" this now by commenting out the member..

But this is not in any way acceptable, I guess..

[vermeeren]

Could you check if this still occurs with latest Sphinx (1.7.5) + Breathe (4.9.0)? Perhaps this has already been fixed silently.

[spookey]

So I tried to build the documentation again

Using breathe 4.7.3 with Sphinx 1.6.7 I get the same error as above:

WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters and qualifiers
  Invalid definition: Expected identifier in nested name, got keyword: bool [error at 4]
    bool Shell::enroll(T * owner, shell_t (T::*)(String) member, String name, String help = "-")
    ----^
If the function has a return type:
  Error in declarator or parameters and qualifiers
  If pointer to member declarator:
    Invalid definition: Expected '::' in pointer to member (function). [error at 18]
      bool Shell::enroll(T * owner, shell_t (T::*)(String) member, String name, String help = "-")
      ------------------^
  If declarator-id:
    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "m". [error at 53]
      bool Shell::enroll(T * owner, shell_t (T::*)(String) member, String name, String help = "-")
      -----------------------------------------------------^

Using breathe 4.9.0 with Sphinx 1.6.7 the error stays the same:

WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters and qualifiers
  Invalid definition: Expected identifier in nested name, got keyword: bool [error at 4]
    bool Shell::enroll(T * owner, shell_t (T::*)(String) member, String name, String help = "-")
    ----^
If the function has a return type:
  Error in declarator or parameters and qualifiers
  If pointer to member declarator:
    Invalid definition: Expected '::' in pointer to member (function). [error at 18]
      bool Shell::enroll(T * owner, shell_t (T::*)(String) member, String name, String help = "-")
      ------------------^
  If declarator-id:
    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "m". [error at 53]
      bool Shell::enroll(T * owner, shell_t (T::*)(String) member, String name, String help = "-")
      -----------------------------------------------------^

Using breathe 4.9.0 with Sphinx 1.7.5 still the same error (along with many other errors):

WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters and qualifiers
  Invalid definition: Expected identifier in nested name, got keyword: bool [error at 4]
    bool Shell::enroll(T * owner, shell_t (T::*)(String) member, String name, String help = "-")
    ----^
If the function has a return type:
  Error in declarator or parameters and qualifiers
  If pointer to member declarator:
    Invalid definition: Expected '::' in pointer to member (function). [error at 18]
      bool Shell::enroll(T * owner, shell_t (T::*)(String) member, String name, String help = "-")
      ------------------^
  If declarator-id:
    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "m". [error at 53]
      bool Shell::enroll(T * owner, shell_t (T::*)(String) member, String name, String help = "-")
      -----------------------------------------------------^

In conclusion - it has not been fixed silently in Sphinx 😢
Anyway, when using any Sphinx Version greater than 1.7 I also have like hundreds of other errors popping up.
Some of them are described here:

• Strange spacing for class members #371
• Error with unnamed structs: WARNING: Invalid definition: Expected identifier in nested name. sphinx-doc/sphinx#2683

Thank you very much.

[mosra]

As far as I'm aware, this problem originates in the Doxygen XML output. In m.css I'm manually patching the function argument list and reinserting the name to proper place -- though in my case it works only for array arguments (such as here), it's not robust enough to handle complex function pointers ... yet.

[vermeeren]

Thanks for the details. For the next step in resolving this issue I would probably like to see some Doxygen XML. Based upon that maybe we can find or file an upstream issue. Otherwise we could implement some workaround for this in Breathe itself.

[mosra]

Taken straight from my tests -- for the following input:

template<class T> int foo(int a, std::string b, char(&things)[5], bool, 
    char(&)[42], int stuff[], double[1337]);

this is the relevant XML snippet:

...
      <memberdef kind="function" id="namespaceFoo_1a438de3b4c677344081baef1ec352f691" prot="public" static="no" const="no" explicit="no" inline="no" virt="non-virtual">
        <templateparamlist>
          <param>
            <type>class T</type>
          </param>
        </templateparamlist>
        <type>int</type>
        <definition>int Foo::foo</definition>
        <argsstring>(int a, std::string b, char(&amp;things)[5], bool, char(&amp;)[42], int stuff[], double[1337])</argsstring>
        <name>foo</name>
        <param>
          <type>int</type>
          <declname>a</declname>
        </param>
        <param>
          <type>std::string</type>
          <declname>b</declname>
        </param>
        <param>
          <type>char(&amp;)</type>
          <declname>things</declname>
          <array>[5]</array>
        </param>
        <param>
          <type>bool</type>
        </param>
        <param>
          <type>char(&amp;)</type>
          <array>[42]</array>
        </param>
        <param>
          <type>int</type>
          <declname>stuff</declname>
          <array>[]</array>
        </param>
        <param>
          <type>double</type>
          <array>[1337]</array>
        </param>
...

You could maybe just use the raw <argsstring>, in my case I didn't want to do all the parsing again so I'm just reshuffling the contents of <param>. I don't think this is a Doxygen bug: it just extracted the parameter name out of it and presented it separately.

[spookey]

Hey there.
to help you a little to figure out what's going on, I build some example project:

https://github.com/spookey/breathe-309

It does not do much, but produces the error above when building documentation...
Hope this helps

[jakobandersen]

I think the problem is the conversion Breathe is doing at get_param_decl() called from visit_function().
Commit 5c466cf seems to fix all the cases of function pointers and references, but the problem is with member function pointers (see @spookey s project, though with T::member replaced by T::*member).
It may be possible to fix it with a more complicated regex (matching ::[:whitespace:]\*?), but XML-decoding the argsstring, using it directly in visit_function(), and getting rid of get_param_decl() seems more robust (assuming argstring exactly captures the arguments).

[vermeeren]

Should be fixed with #512, released in Breathe v4.17.0. Note that you also need Sphinx 3.x for recent Breathe versions.