Правильное использование Doxygen

Я безуспешно пытался задокументировать свой проект C ++ с помощью Doxygen: Doxygen не распознает определенные макросы, и, следовательно, целые функции неправильно интерпретируются, и большую часть времени не генерирует документы, даже если у них есть специальные блоки комментариев. Дело в точке:

/**
 * \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;
    }
};

В документации, созданной для вышеуказанного класса, всегда отсутствует описание для doNothing, а IN интерпретируется как функция! Я что-то здесь делаю не так?


c++ doxygen
person themoondothshine    schedule 15.04.2010    source источник
comment
Каковы значения MACRO_EXPANSION et al. (doxygen.nl/config.html#cfg_macro_expansion) в вашем файле конфигурации?   -  person Éric Malenfant    schedule 15.04.2010
comment
@Eric: Думаю, ты сразу понял проблему! MACRO_EXPANSION имеет значение YES, но нужно ли мне также указывать дополнительные подключаемые каталоги? В настоящее время все используемые заголовки также обрабатываются Doxygen. Я проверю остальные параметры и вернусь к вам.   -  person themoondothshine    schedule 15.04.2010
comment
Вот параметры конфигурации: ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = NO SEARCH_INCLUDES = YES   -  person themoondothshine    schedule 15.04.2010

Ответы (1)


arrow_upward
4
arrow_downward

Две вещи:

1) Парсер Doxygen не «видит» IN в doNothing (так как он удаляется на этапе предварительной обработки), поэтому \ fn не должен включать его: const char* doNothing(const char* s). Кстати, в этом \ fn нет необходимости: Doxygen автоматически связывает комментарий, если он находится непосредственно перед документированным объектом.

2) Я не знаю, во что расширяется __SXC_FUNCTION_ATTRIBUTE, но, если это что-то похожее на __MYLIB_FUNCTION_ATTRIBUTE, это, вероятно, сбивает Doxygen. В качестве обходного пути вы можете либо определить эти макросы как ничего в разделе PREDEFINED конфигурационного файла Doxygen, либо условно определить их в источниках, например:

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

и поместите PREDEFINED = DOXYGEN в свой файл конфигурации.

person Éric Malenfant    schedule 15.04.2010
comment
@Eric: Замечательно !! Ваше решение сработало как ветер! Это определенно +1. Спасибо. - person themoondothshine; 16.04.2010