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

doxygenIniziare con doxygen


Osservazioni

Questa sezione fornisce una panoramica di cosa sia Doxygen e perché uno sviluppatore potrebbe volerlo utilizzare.

Dovrebbe anche menzionare tutti i soggetti di grandi dimensioni all'interno di doxygen e collegarsi agli argomenti correlati. Poiché la documentazione di doxygen è nuova, potrebbe essere necessario creare versioni iniziali di tali argomenti correlati.

Commentando il tuo codice

Esistono diversi modi per contrassegnare un blocco di commenti come una descrizione dettagliata, in modo che questo blocco di commenti sia analizzato da Doxygen e aggiunto come descrizione del seguente codice alla documentazione. Il primo e il più comune sono i commenti in stile C con un asterisco in più nella sequenza di avvio del commento, ad esempio:

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

L'alternativa successiva è usare lo stile Qt e aggiungere un punto esclamativo (!) Dopo la sequenza di apertura di un blocco di commenti in stile C:

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

Una terza alternativa consiste nell'utilizzare un blocco di almeno due righe di commento C ++, in cui ogni riga inizia con una barra aggiuntiva o un punto esclamativo:

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

o

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

Ad alcune persone piace rendere i blocchi dei commenti più visibili nella documentazione. A tale scopo è possibile utilizzare quanto segue:

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

Nota le 2 barre per terminare il normale blocco di commenti e avviare un blocco di commenti speciale.

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

Per strutturare e analizzare la documentazione generata, Doxygen fornisce un numero elevato (> 170) di comandi speciali. Tutti i comandi nella documentazione iniziano con un backslash () o un at-sign (@).

Per esempio

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

è equivalente a

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

Per la breve descrizione ci sono anche diverse possibilità:

Si potrebbe usare il comando \brief con uno dei blocchi di commento sopra. Questo comando termina alla fine di un paragrafo, quindi la descrizione dettagliata segue una riga vuota.

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

Se JAVADOC_AUTOBRIEF è impostato su YES nel file di configurazione, i blocchi di commento in stile JavaDoc inizieranno automaticamente una breve descrizione che termina con il primo punto seguito da uno spazio o una nuova riga.

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

E infine ecco un esempio per una documentazione completa di una funzione con 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 */
}
 

fonte e maggiori informazioni sulla homepage di Doxygen

Installazione o configurazione

Istruzioni dettagliate su come installare o installare doxygen.