Usando Doxygen Correctamente

Question

He estado intentando documentar mi proyecto C++ usando Doxygen, con poco éxito: Doxygen falla al reconocer ciertas macros, y consecuentemente, las funciones enteras son malinterpretadas y la mayoría de las veces no genera documentos aunque tengan bloques de comentarios especiales . El caso en cuestión:

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

documentación generada por la clase anterior siempre le falta una descripción de doNothing y IN se interpreta como una función! ¿Estoy haciendo algo mal aquí?

Answer 1

dos cosas:

1) El analizador Doxygen no "ve" el "IN" en DoNothing (ya que se elimina en la fase de pre-procesamiento), por lo que el \ fn no debe incluirlo: const char* doNothing(const char* s). Por cierto, esto \ fn no es necesario: Doxygen asocia automáticamente el comentario si está inmediatamente antes de la entidad documentada.

2) No sé en qué se expande __SXC_FUNCTION_ATTRIBUTE pero, si es algo similar a __MYLIB_FUNCTION_ATTRIBUTE, probablemente confunda Doxygen. Como solución, puede o bien definir estas macros a nada en la sección predefinida del archivo de configuración de Doxygen, o condicionalmente definirlos en las fuentes, así:

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

y poner PREDEFINIDAS = Doxygen en su archivo de configuración.