[Doxygen-users] help with macros

[Burlen L. <bl...@lb...>]

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!