Sphinx: WARNING message is not clear

[tkoyama010]

Is your feature request related to a problem? Please describe.
I'm frustrated when reading this warning message.

/home/ubuntu/getfem/doc/sphinx/source/userdoc/model_object.rst:167: WARNING: Error in declarator
If declId and parameters:
Invalid definition: Expected identifier in nested name. [error at 11]
complex_rhs()
-----------^
If parenthesis in noptr-declarator:
Error in declarator or parameters
Invalid definition: Expected identifier in nested name. [error at 12]
complex_rhs()
------------^

It means that return type is not defined. But I couldn't get it.

Describe the solution you'd like
Could you give me a message "You don't define return type."?

Describe alternatives you've considered
None

Additional context
How to reproduce warning.
$ git clone https://github.com/getfem-doc/getfem.git
$ cd getfem
$ git checkout 45b86c7fe8e0c2e694d2dd94b867baabb2a03055
$ bash autogen.sh
$ ./configure
$ make -j8
$ make html

[jakobandersen]

This is with a C declaration, right? A c:function directive? It is indeed a rather technical message, but I'm not sure how to improve it.

The second alternative in the error indicates that you could have meant something like complex_rhs (*f)(int arg) instead of what I guess was meant void complex_rhs(). The third option is complex_rhs f(int arg), which the first error alternative tries to hint at.

[tkoyama010]

@jakobandersen Thank you for your comment. What you said in your comment is exactly what I wanted in warning message. I think message will be better if it shows the example of definition rather than a word "identifier".

[jakobandersen]

The technical terms used are in general based on the grammar for C (or C++) to avoid inventing new terms. In this case those terms are "delcarator", "declarator-id", "parameters", "noptr-declarator", "identifier", and "nested name".
I have merged #7376, so the message is now something like the following, which includes relatively simple examples of the shape of declaration which was expected.

/path/to/file.rst:42: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 3]
    foo()
    ---^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expected identifier in nested name. [error at 4]
    foo()
    ----^

Do you believe this would have made it easier to figure out the issue?

[tkoyama010]

Thanks.

[jakobandersen]

Great, feel free to open further issues if you find strange error messages.