Search code examples
cheader-filesdoxygen-wizardxc16

__inline__ and __attribute__ confusing Doxygen

(SOLVED, see the solution at the end)

I'm on an embedded C project and have written a .h file with only static forced inline functions. I have documented them like this:

//----------------------------------------------------------------------------
// RECT WIDTH
/** Returns a source rectangle's width.
 *  The RECT_Width method calculates and returns a source rectangle's width.
 * 
 * @param r  A RECT structure that contains the specified source rectangle.
 * @return   The source rectangle's width.
 */
FORCE_INLINE __attribute__((unused))
static COORD RECT_Width(RECT r) {
    return r.Right-r.Left;
}

FORCE_INLINE is defined as

#define FORCE_INLINE  __attribute__((always_inline))

The problem line will be expanded as:

__attribute__((always_inline)) __attribute__((unused))

__attribute__ has been added to the EXCLUDE_SYSMBOLS section so they will not be documented as functions.

The problem is that Doxygen seems to get confused by the line FORCE_INLINE __attribute__((unused)). It seems like it gets out of sync and skips almost every function except for one, in the middle of the file. That function is formatted exactly the same as everyone else.

Doxygen also documents parts of some functions' parameters and fragments of code as global variables.

FORCE_INLINE RECT   r2
r   Left = MAX(r1.Left,r2.Left)
r   Top = MAX(r1.Top,r2.Top)
r   Right = MIN(r1.Right,r2.Right)
r   Bottom = MIN(r1.Bottom,r2.Bottom)
return  r
FORCE_INLINE POINT  p
FORCE_INLINE COORD  offset
FORCE_INLINE POINT  pos

I also tried to turn on MACRO_EXPANSION, EXPAND_ONLY_PREDEF and add FORCE_INLINE to the EXPAND_AS_DEFINED section. No difference.

I have also tried to add them to EXCLUDE_SYSMBOLS:

FORCE_INLINE
__attribute__

As a test I added the @fn command to one of the functions not seen by Doxygen and all documentation for that function was generated. But I can't add @fn to every function and have fragments of code documented as global variables.

Does anyone have an idea of how to make Doxygen to ignore the FORCE_INLINE __attribute__((unused)) in front of each function?

SOLUTION
@KamilCuk gave me an idea so I added this to my header file:

#if __DOXYGEN__
    #define FORCE_INLINE_SILENT
#else
    #define FORCE_INLINE_SILENT FORCE_INLINE __attribute__((unused))
#endif

and then replaced FORCE_INLINE __attribute__((unused)) with FORCE_INLINE_SILENT. FORCE_INLINE is defined in another header file.

Solution

  • The problem is that Doxygen seems to get confused by the line FORCE_INLINE attribute((unused))

    And you should handle that so that it does not get confused. For example:

    #if __GNUC__
#define FORCE_INLINE  __attribute__((always_inline))
#else
// expands to nothing for others
#define FORCE_INLINE
#endif

    or like:

    #if __DOXYGEN__
#define FORCE_INLINE
#endif

    That way, doxygen will see nothing. You need to handle __attribute__((unused)) that way also and typically put such macros in a common header providing compatibility of your project to different compilers.