Doxygen C preprocessor macros documentation style

Question

I just noticed something interesting about the way Doxygen generates documentation for C preprocessor macros. Of the three styles of creating block comments in Doxygen's manual (///, //! and /** */, only the former two styles (///, //!) will show the brief description on the file's macro list.

My question is: is this by design? I there a configuration option that controls this? I couldn't find any information that the Javadoc style should behave differently from the Qt and C++ styles.

I tried using the MULTILINE_CPP_IS_BRIEF config option but that didn't have any effect.

test.c

/**
 * @file test.c
 * @brief A test
 */

#include <stdio.h>

/** This is a define that doesn't have a brief explanation on the macro list */
#define DEFINE_A   1 
/// This is another define, it's brief explanation appears on the file's macro list
#define DEFINE_B   2
//! This is another define, it's brief explanation appears on the file's macro list
#define DEFINE_C   3 

#define DEFINE_D   4 /**<  This is a define that doesn't have a brief explanation on the file's macro list */
#define DEFINE_F   4 ///< This is another define, it's brief explanation appears on the file's macro list
#define DEFINE_G   4 //!< This is another define, it's brief explanation appears on the file's macro list

/**
 * A simple test function
 *
 * @param[in] x An integer argument
 * @return always zero
 */
int test_fcn( int x )
{
    return x*x;
}

int main(void)
{
    return test_fcn( 3 );
}

test.h

/** @file */

/**My Preprocessor Macro.*/ 
#define TEST_DEFINE(x) (x*x) 

/**
 * @defgroup TEST_GROUP Test Group
 *
 * @{
 */

/** Test AAA documentation. */
#define TEST_AAA (1)
/** Test BBB documentation. */
#define TEST_BBB (2)
/** Test CCC documentation. */
#define TEST_CCC (3)
/** @} */

Doxyfile

PROJECT_NAME           = "test"
OUTPUT_DIRECTORY       = doc_out
INPUT                  = test.c test.h
#MULTILINE_CPP_IS_BRIEF = NO
MULTILINE_CPP_IS_BRIEF = YES

I'm using Doxygen 1.8.15 on Windows 7 64 bits.

Thanks!

Leonardo Leonardo · Accepted Answer · 2019-02-21T16:12:41

Asked too fast. The option that I'm looking for is JAVADOC_AUTOBRIEF=YES.

There's one curious thing though. These are supposed to be the default values for

JAVADOC_AUTOBRIEF      = NO
QT_AUTOBRIEF           = NO
MULTILINE_CPP_IS_BRIEF = NO

But the actual default behaviour is

JAVADOC_AUTOBRIEF      = NO
QT_AUTOBRIEF           = YES
MULTILINE_CPP_IS_BRIEF = YES

If I use the following options on my Doxygen file:

JAVADOC_AUTOBRIEF      = NO
QT_AUTOBRIEF           = NO
MULTILINE_CPP_IS_BRIEF = NO

I get different behaviour from Javadoc, Qt and C++ styles, and I feel this is wrong.

Thanks!

P.S.:

Doxygen -x against the following Doxyfile:

PROJECT_NAME           = "test"
OUTPUT_DIRECTORY       = doc_out
INPUT                  = test.c test.h
JAVADOC_AUTOBRIEF      = YES
QT_AUTOBRIEF           = NO
MULTILINE_CPP_IS_BRIEF = NO

Gives:

# doxygen.exe -x Doxyfile
# Difference with default Doxyfile 1.8.15
PROJECT_NAME           = test
OUTPUT_DIRECTORY       = doc_out
JAVADOC_AUTOBRIEF      = YES
INPUT                  = test.c \
                         test.h

It seems that QT_AUTOBRIEF is not doing anything (I get brief descriptions for DEFINE_C and DEFINE_G even when QT_AUTOBRIEF=NO).

Thanks!

Doxygen C preprocessor macros documentation style

1 Answers