Я пытался зарегистрировать свой проект 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
интерпретируется как функция! Я делаю что-то не так здесь?
Две вещи:
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 в ваш конфигурационный файл.