Стиль документации макросов препроцессора Doxygen C - PullRequest
Новая
       45

Стиль документации макросов препроцессора Doxygen C

0 голосов
/ 21 февраля 2019

Я только что заметил кое-что интересное в том, как Doxygen генерирует документацию для макросов препроцессора Си.Из трех стилей создания блочных комментариев в руководстве Doxygen (///, //! и /** */) только первые два стиля (///, //!) будут отображать краткое описание насписок макросов файла.

Мой вопрос: это по замыслу? У меня есть параметр конфигурации, который управляет этим? Я не смог найти никакой информации о том, что стиль Javadoc должен вести себя иначе, чем стили Qt и C ++.

Я пытался использовать опцию конфигурации MULTILINE_CPP_IS_BRIEF, но это не имело никакого эффекта.

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

Я использую Doxygen 1.8.15 на 64-битной Windows 7.

Спасибо!

1 Ответ

0 голосов
/ 21 февраля 2019

Спросил слишком быстро.Вариант, который я ищу: JAVADOC_AUTOBRIEF=YES.

Есть одна любопытная вещь.Предполагается, что это значения по умолчанию для 

JAVADOC_AUTOBRIEF      = NO
QT_AUTOBRIEF           = NO
MULTILINE_CPP_IS_BRIEF = NO

Но поведение по умолчанию фактическое равно 

JAVADOC_AUTOBRIEF      = NO
QT_AUTOBRIEF           = YES
MULTILINE_CPP_IS_BRIEF = YES

Если я использую следующие параметры в моем файле Doxygen:

JAVADOC_AUTOBRIEF      = NO
QT_AUTOBRIEF           = NO
MULTILINE_CPP_IS_BRIEF = NO

Я получаю другое поведение от стилей Javadoc, Qt и C ++, и я чувствую, что это неправильно.

Спасибо!

PS:

Doxygen -x против следующего Doxyfile: 

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

Дает: 

# 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

Кажется, что QT_AUTOBRIEF ничего не делает (я получаю краткие описания для DEFINE_C и DEFINE_G даже когда QT_AUTOBRIEF=NO).

Спасибо!

...