Warnings

[blitz-research]

Hi,

I'm just starting out with sphinx/breathe after having used plain doxygen for a while now, and I'm finding I'm getting a number of strange warnings when it builds:

If the function has no return type:
  Error in declarator or parameters-and-qualifiers
  Invalid C++ declaration: Expecting "(" in parameters-and-qualifiers. [error at 8]
    SGD_API void SGD_DECL sgd_Init ()
    --------^
If the function has a return type:
  Error in declarator or parameters-and-qualifiers
  If pointer to member declarator:
    Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 12]
      SGD_API void SGD_DECL sgd_Init ()
      ------------^
  If declarator-id:
    Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 12]
      SGD_API void SGD_DECL sgd_Init ()

The problem seems to be the SGD_API and SGD_DECL #defines. If I remove these, the warning goes away, but even simplying them to just:

#define SGD_API extern "C"
#define SGD_DECL

still causes warnings.

It doesn't seem to be causing any problems but it makes my cmake output very noisy as this warning happens for every function decl in my header file. Hmmm, thinking about it now, perhaps it doesn't like 'extern "C"' on the same line as a decl?

Should I be worried about this warning and, if not, can I disable it?

Apart from this, spinx/breathe is working great so far!

Bye,
Mark

[blitz-research]

OK, maybe this is worse than I thought, I can't get :ref:sgd_Init in the .rst file to work, I get WARNING: undefined label: 'sgd_init' [ref.ref]

sgd_Init() does appear in output docs, but perhaps it's broken due to the warning above?

Also curious that the warning has lowercased the identifier.

[blitz-research]

OK, I need to use :any: not :ref: and I need to manually strip macros from the header or :any: fails too due to the above warnings I guess.

It thought doxygen was supposed to deal with the parsing? Doxygen can handle the same header just fine so it seems weird it can break breathe so easily.

[blitz-research]

OK, I have a fairly clean solution to this issue: you need to modify your Doxyfile to get doxygen to replace any macros used in your header decls with empty space, eg:

ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF  = YES
PREDEFINED = SGD_API= SGD_DECL=

This will effectively remove the macros from decls like SGD_API void SGD_DECL sgd_Init();

[jakobandersen]

The reason for the warning is that Sphinx can't do pre-processing, and Breathe doesn't know about it either. However, there is an escape hatch, to tell the parser to consider certain things as attributes:: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-cpp_id_attributes
Try in your Sphinx configuration add something like cpp_id_attributes = ["SGD_API", "SGD_DECL"], then it should work.
Though, if you don't want those macros in the documentation at all, then your approach with Doxyfile seems like the right one.

[blitz-research]

Hi, thanks for the reply, I hadn't actually noticed SGD_API and SGD_DECL had been removed - I think I prefer it that way but good to know I can get them back!