Looking for doxygen Answers? Try Ask4KnowledgeBase
Looking for doxygen Keywords? Try Ask4Keywords

doxygenErste Schritte mit doxygen


Bemerkungen

In diesem Abschnitt erhalten Sie einen Überblick darüber, was Doxygen ist und warum ein Entwickler es möglicherweise verwenden möchte.

Es sollte auch alle großen Themen innerhalb von Sauerstoff erwähnen und auf die verwandten Themen verweisen. Da die Dokumentation für doxygen neu ist, müssen Sie möglicherweise erste Versionen dieser verwandten Themen erstellen.

Kommentieren Sie Ihren Code

Es gibt mehrere Möglichkeiten, einen Kommentarblock als detaillierte Beschreibung zu markieren, sodass dieser Kommentarblock von Doxygen analysiert und der Dokumentation als Beschreibung des folgenden Codeelements hinzugefügt wird. Der erste und häufigste Kommentar sind Kommentare im C-Stil mit einem zusätzlichen Stern in der Kommentar-Startsequenz, z. B .:

/**
 * … text …
 */
int dummy_var;
 

Die nächste Alternative ist, den Qt-Stil zu verwenden und nach der Anfangssequenz eines Kommentarblocks im C-Stil ein Ausrufezeichen (!) Hinzuzufügen:

/*!
 * … text …
 */
void foo(void);
 

Eine dritte Alternative ist die Verwendung eines Blocks aus mindestens zwei C ++ - Kommentarzeilen, wobei jede Zeile mit einem zusätzlichen Schrägstrich oder einem Ausrufezeichen beginnt:

/// 
/// ... text ... 
///
 

oder

//! 
//! ... text ... 
//!
 

Einige Leute möchten ihre Kommentarblöcke in der Dokumentation besser sichtbar machen. Zu diesem Zweck können Sie Folgendes verwenden:

 /********************************************//** 
  * ... text 
  ***********************************************/
 

Beachten Sie die 2 Schrägstriche, um den normalen Kommentarblock zu beenden und einen speziellen Kommentarblock zu starten.

/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
 

Zur Strukturierung und Anpassung der generierten Dokumentation bietet Doxygen eine große Anzahl (> 170) Spezialbefehle. Alle Befehle in der Dokumentation beginnen mit einem umgekehrten Schrägstrich () oder einem At-Zeichen (@).

Zum Beispiel

/**
 * \brief    A brief description in one short sentence.
 */
 

ist äquivalent zu

/**
 * @brief    A brief description in one short sentence.
 */
 

Für die Kurzbeschreibung gibt es auch mehrere Möglichkeiten:

Man könnte den Befehl \brief mit einem der obigen Kommentarblöcke verwenden. Dieser Befehl endet am Ende eines Absatzes, daher folgt die detaillierte Beschreibung nach einer leeren Zeile.

/** \brief Brief description. 
 * Brief description continued. 
 * 
 * Detailed description starts here. 
 */ 
 

Wenn JAVADOC_AUTOBRIEF in der Konfigurationsdatei auf YES JAVADOC_AUTOBRIEF ist, beginnen Kommentarblöcke im JavaDoc-Stil automatisch mit einer kurzen Beschreibung, die am ersten Punkt endet, gefolgt von einem Leerzeichen oder einer neuen Zeile.

/// Brief description which ends at this dot. Details follow 
/// here. 
 

Und zum Abschluss noch ein Beispiel für eine vollständige Dokumentation einer Funktion mit doxygen:

/**
 * \brief   The function bar. 
 *
 * \details This function does something which is doing nothing. So this text
 *          is totally senseless and you really do not need to read this,
 *          because this text is basically saying nothing.
 *
 * \note    This text shall only show you, how such a \"note\" section
 *          is looking. There is nothing which really needs your notice,
 *          so you do not really need to read this section.
 *
 * \param[in]     a    Description of parameter a.
 * \param[out]    b    Description of the parameter b.
 * \param[in,out] c    Description of the parameter c.
 *
 * \return        The error return code of the function.
 *
 * \retval        ERR_SUCCESS    The function is successfully executed
 * \retval        ERR_FAILURE    An error occurred
 */

errcode_t bar(int a, int b, int c)
{    
    /** More detailed description inside the code */
}
 

Quelle und weitere Informationen auf der Doxygen-Homepage

Installation oder Setup

Ausführliche Anweisungen zum Einrichten oder Installieren von doxygen.