doxygenAan de slag met doxygen


Opmerkingen

Deze sectie geeft een overzicht van wat doxygen is en waarom een ontwikkelaar het misschien wil gebruiken.

Het moet ook alle grote onderwerpen binnen doxygen vermelden en een link naar de gerelateerde onderwerpen bevatten. Aangezien de documentatie voor doxygen nieuw is, moet u mogelijk eerste versies van die gerelateerde onderwerpen maken.

Reageren op uw code

Er zijn verschillende manieren om een commentaarblok als een gedetailleerde beschrijving te markeren, zodat dit commentaarblok door Doxygen wordt geparseerd en als een beschrijving van het volgende code-item aan de documentatie wordt toegevoegd. De eerste en meest voorkomende zijn opmerkingen in C-stijl met een extra sterretje in de startreeks voor opmerkingen, bijvoorbeeld:

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

Het volgende alternatief is om de Qt-stijl te gebruiken en een uitroepteken (!) Toe te voegen na de openingsvolgorde van een C-stijl commentaarblok:

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

Een derde alternatief is om een blok van minimaal twee C ++ commentaarregels te gebruiken, waarbij elke regel begint met een extra schuine streep of een uitroepteken:

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

of

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

Sommige mensen maken graag hun blokken met opmerkingen zichtbaarder in de documentatie. Voor dit doel kunt u het volgende gebruiken:

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

Let op de 2 schuine strepen om het normale opmerkingenblok te beëindigen en een speciaal opmerkingenblok te starten.

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

Doxygen biedt een groot aantal (> 170) speciale commando's om de gegenereerde documentatie te structureren en fomat. Alle opdrachten in de documentatie beginnen met een backslash () of een apenstaartje (@).

Bijvoorbeeld

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

is gelijk aan

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

Voor de korte beschrijving zijn er ook verschillende mogelijkheden:

Je zou het \brief commando kunnen gebruiken met een van de bovenstaande commentaarblokken. Deze opdracht eindigt aan het einde van een alinea, dus de gedetailleerde beschrijving volgt na een lege regel.

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

Als JAVADOC_AUTOBRIEF is ingesteld op YES in het configuratiebestand, wordt met behulp van commentaarblokken in JavaDoc-stijl automatisch een korte beschrijving gestart die eindigt bij de eerste punt gevolgd door een spatie of een nieuwe regel.

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

En tot slot hier een voorbeeld voor een volledige documentatie van een functie met 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 */
}
 

bron en meer info op de Doxygen-startpagina

Installatie of instellingen

Gedetailleerde instructies voor het instellen of installeren van doxygen.