We are integrating Doxygen into a large existing C++ project. The
project make extensive use of macros in certain inheritance hierarchies
where consistency of interface and implementation are required. This
seems to be causing Doxygen some trouble. The problem I'm having is that
no related errors or warnings are emitted. I'm stuck, and not sure how
to get some actionable info about what the problem and solution might be.
Here's an example of such a macro
#define TECA_ALGORITHM_PROPERTY(T, NAME) \
\
/** Set the value of the NAME algorithm property */ \
void set_##NAME(const T &v) \
{ \
if (this->NAME != v) \
{ \
this->NAME = v; \
this->set_modified(); \
} \
} \
\
/** Get the value of the NAME algorithm property */ \
const T &get_##NAME() const \
{ \
return this->NAME; \
}
For context, a link to its definition in the code base (a number of
similar macros are defined there as well)
https://github.com/LBL-EESA/TECA/blob/8d19be022df763e6d2c2fb8e83f56be3ef9ee897/core/teca_algorithm.h#L84
Where this macro is used in a class we want to Doxygen the use, by
having a group like this:
/** @name files_regex
* Set a regular expression identifying the set of files
comprising the
* dataset. This should contain the full path to the files and
the regular
* expression. Only the final component of a path may contain
a regex.
* Be aware that regular expression control characters do not
have the
* same meaning as shell glob control characters. When used in
a shell
* regular expression control characters need to be quoted or
escaped to
* prevent the shell from interpreting them.
*/
///@{
TECA_ALGORITHM_PROPERTY(std::string, files_regex)
///@}
For context here is the use in class definition:
https://github.com/LBL-EESA/TECA/blob/8d19be022df763e6d2c2fb8e83f56be3ef9ee897/io/teca_cf_reader.h#L99
The resulting Doxygen web pages however do not include any of the class
methods, only the brief and detailed class description.
https://teca.readthedocs.io/en/integrating_breathe/doxygen/classteca__cf__reader.html
no warning or error are emitted.
I've tried various Doxyfile settings, here is what I'm using
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = NO
SKIP_FUNCTION_MACROS = YES
I experimented with
SKIP_FUNCTION_MACROS = NO
However, with SKIP_FUNCTION_MACROS = NO any class that used the macros
was dropped from the site entirely. There were many warnings issued on
the class constructors about the macro not ending in a semi colon. I
don't understand why macros would end in a semi colon as that's not a
language requirement and makes no sense for defining functions like the
macros in question here do - the appropriate terminating character is }
not ;. Not sure how to work around that.
My questions are: Should Doxygen be able to handle this? Does anyone
know what the issue might be? If not how could we get some actionable
info about the failures?
Thank you!
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
