Using Doxygen Correctly

Question

I have been trying to document my C++ project using Doxygen, with little success: Doxygen to fails recognize certain macros, and consequently entire functions are misinterpreted and most of time does not generate docs even though they have special comment blocks. Case in point:

/**
 * \def      __MYLIB_FUNCTION_ATTRIBUTE(...)
 * \brief    Some brief comment
 * \details  Detailed doc
 * \sa       Some valid references
 */
#define __MYLIB_FUNCTION_ATTRIBUTE(...)    __attribute__(__VA_ARGS__)

/**
 * \def      IN
 * \brief    Tag for input arguments to a function
 * \details  Blah...
 * \sa       OUT
 */
#define IN

/**
 * \def      OUT
 * \brief    Tag for output arguments to a function
 * \details  Blah...
 * \sa       IN
 */
#define OUT

class MyClass {
public:

    /**
     * \fn        MyClass()
     * \brief     Constructor for MyClass
     * \details   Hi!
     */
    __MYLIB_FUNCTION_ATTRIBUTE(__always_inline__)
    MyClass() {
    }

    /**
     * \fn        const char *doNothing(const char *s IN)
     * \brief     A weird function
     * \details   Some very weird doc
     * \param[in] s No good parameter
     */
    const char* __SXC_FUNCTION_ATTRIBUTE(__const__) doNothing(const char *s IN) {
        return s;
    }
};

Documentation generated for the above class is always missing a description for doNothing and IN is interpreted as a function! Am I doing something wrong here?

Answer 1

Two things:

1) The Doxygen parser does not "see" the "IN" in doNothing (since it is removed in the preprocessing phase), so the \fn should not include it: const char* doNothing(const char* s). BTW, this \fn is not necessary: Doxygen automatically associates the comment if it is immediately before the documented entity.

2) I don't know what __SXC_FUNCTION_ATTRIBUTE expands into but, if it is something similar to __MYLIB_FUNCTION_ATTRIBUTE, it probably confuses Doxygen. As a workaround, you could either define these macros to nothing in the PREDEFINED section of Doxygen's config file, or conditionally define them in the sources, like this:

#ifdef DOXYGEN
// Doxygen does not grok the normal definition of this
#define  __MYLIB_FUNCTION_ATTRIBUTE(...)
#else
#define __MYLIB_FUNCTION_ATTRIBUTE(...)    __attribute__(__VA_ARGS__)
#endif

and put PREDEFINED = DOXYGEN in your config file.