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?

What are the values of MACRO_EXPANSION et al. (doxygen.nl/config.html#cfg_macro_expansion) in your config file? — Éric Malenfant
– Éric Malenfant, Commented Apr 15, 2010 at 15:51
@Eric: I think you caught on to the problem head on! MACRO_EXPANSION is set to YES, but do I need to also specify additional include directories? Currently all the headers used are also processed by Doxygen. I'll review the rest of the parameters and get back to you. — themoondothshine
– themoondothshine, Commented Apr 15, 2010 at 15:59
Here are the config params: ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = NO SEARCH_INCLUDES = YES — themoondothshine
– themoondothshine, Commented Apr 15, 2010 at 16:07

Éric Malenfant · Accepted Answer · 2010-04-15 17:57:27Z

4

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.

answered Apr 15, 2010 at 17:57

Éric Malenfant

14.2k42 silver badges42 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

themoondothshine Over a year ago

@Eric: Awesome!! Your solution worked like a breeze! That's definitely a +1. Thanks.

Collectives™ on Stack Overflow

Using Doxygen Correctly

1 Answer 1

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related