Doxygen korrekt verwenden

Question

Ich habe versucht, mein C++ - Projekt mit Doxygen zu dokumentieren, mit wenig Erfolg: Doxygen erkennt bestimmte Makros nicht und folglich werden ganze Funktionen falsch interpretiert und die meiste Zeit erzeugt keine Dokumente, obwohl sie spezielle Kommentarblöcke haben . Typischer Fall:

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

Dokumentation für die obige Klasse erzeugt wird, immer eine Beschreibung für doNothing und IN fehlt als Funktion interpretiert! Mache ich hier etwas falsch?

Answer 1

Zwei Dinge:

1) Der Doxygen-Parser "sehen", nicht den "IN" in DoNothing (da es in der Vorlaufphase) entfernt wird, so dass der \ fn nicht enthalten soll: const char* doNothing(const char* s). Übrigens ist dies nicht notwendig: Doxygen ordnet den Kommentar automatisch zu, wenn er sich unmittelbar vor der dokumentierten Entität befindet.

2) Ich weiß nicht, was __SXC_FUNCTION_ATTRIBUTE expandiert, aber wenn es ähnlich wie __MYLIB_FUNCTION_ATTRIBUTE ist, verwirrt es wahrscheinlich 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 

und setzen PREDEFINED = doxygen in Ihrer Konfigurationsdatei: Zur Umgehung des Problems können Sie entweder diese Makros nichts im PREDEFINED Abschnitt von Doxygen config-Datei oder bedingt definieren sie in den Quellen, wie diese definieren.