Используйте Doxygen для документирования функции, отправляемой в MACRO C ++ - PullRequest
Новая
       28

Используйте Doxygen для документирования функции, отправляемой в MACRO C ++

2 голосов
/ 08 ноября 2011

Недавно мы добавили некоторый код для обозначения устаревшего кода во время компиляции с использованием MACROS.Теперь Doxygen не документирует устаревшие функции должным образом.

    #if defined(__GNUC__)
    #define DEPRECATED(func) func __attribute__((deprecated)) /**< mark a function as deprecated in gcc. */ 

    #elif defined(_MSC_VER)
    #define DEPRECATED(func) __declspec(deprecated) func /**< mark a function as deprecated in msvc. */
    #endif

Обратите внимание, что это упрощенная версия макросов для этого поста, реальные макросы проверяют версию компилятора и т.д.функция устарела, поэтому выдается предупреждение компилятора. 

    /**
     * myMethod() is deprecated.
     */
    DEPRECATED(
        /**
         * @deprecated
         * Description of deprecated function
         * 
         * @param var this is a parameter
         *
         * @return this is returned 
         */
        int myMethod(int var)
    );

Проблема в том, что Doxygen хочет показать документацию для DEPRECATED, а не для myMethod (int var).

Кто-нибудь знает, как заставить Doxygen документировать myMethod, а не макрос УСТАРЕЛО?

Ответы [ 2 ]

3 голосов
/ 08 ноября 2011

Вы должны сказать doxygen, что он должен удалить макрос DEPRECATED. Вы можете сделать это, используя следующие параметры препроцессора в файле конфигурации: 

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
PREDEFINED             = "DEPRECATED(x)=x"

Вы можете отладить результат предварительной обработки, запустив doxygen с опцией -d Preprocessor. Когда эта опция присутствует, Doxygen будет выводить входной файл на выход после выполнения предварительной обработки.

Подробнее см. http://www.doxygen.org/preprocessing.html

1 голос
/ 08 ноября 2011

Используйте тег @ fn , чтобы явно указать, на что ссылается блок. Не так удобно, как неявное соединение, но безопаснее.

...