C ++: Creazione di documentazione con Doxygen - dummies

La maggior parte dei programmatori odia creare documentazione più di quanto detesti commentare il proprio codice. Inserisci Doxygen, che consente ai programmatori di incorporare tag nei commenti che possono essere successivamente estratti per creare la documentazione.

Installazione di Doxygen

Doxygen non viene fornito con Codice:: Blocchi (almeno non al momento della stesura di questo documento). Dovrai scaricare la versione corretta di Doxygen per la tua applicazione. (C'è anche un collegamento al sito Web di Doxygen dal codice: sito Blocchi.) Dopo aver effettuato il collegamento al sito Web Doxygenorg, è possibile accedere alla pagina di download e trovare la versione di Doxygen per il proprio sistema operativo, come illustrato di seguito:

Scarica e installa la versione adatta al tuo sistema operativo. È possibile accettare i valori predefiniti, ma ricordare dove la procedura guidata di installazione inserisce il file eseguibile di Doxygen.

Ora inizia il codice:: Blocchi. Seleziona DoxyBlocks → Apri preferenze. Da lì selezionare la scheda Generale e impostare il percorso su Doxygen. (Questo è il percorso annotato nel paragrafo precedente.) Il percorso predefinito per Windows è C: Program Filesdoxygenbindoxygen. exe. Fai lo stesso per il percorso di Doxywizard. Qui il valore predefinito per Windows è C: Program Filesdoxygenbindoxywizard. exe . È possibile lasciare gli altri strumenti vuoti in quanto non sono necessari quando si genera la documentazione in formato HTML.

Aggiunta di commenti alla documentazione

Doxygen utilizza commenti speciali per contrassegnare le parole chiave che aiutano lo strumento a creare documentazione. Abbastanza confidando, Doxygen accetta diversi standard diversi, ma il default è quello che assomiglia di più a JavaDoc, il commento / ** , che va bene. (È possibile modificare lo stile di commento in uno degli altri selezionando DoxyBlocks → Apri preferenze e quindi selezionando la scheda Stile commento.)

Per vedere come funziona, posiziona il cursore all'inizio di una funzione e seleziona DoxyBlocks → Block Comment (o premi Ctrl + Alt + B). Viene visualizzato un commento simile al seguente (i seguenti esempi utilizzano il programma Budget5 che viene visualizzato nel materiale scaricabile all'indirizzo www. Dummies. Com / extras / cplusplus):

/ ** breve * * lista accList param e * return void * * / void getAccounts (list & accList) {

Code:: Blocks inserisce un commento del blocco Doxygen a partire da / **. Doxygen sa che questo commento appartiene alla definizione della funzione che segue immediatamente. Le parole chiave di Doxygen iniziano con (barra retroversa). La breve parola chiave contrassegna la breve descrizione della funzione. La breve descrizione può estendersi su più di una riga.Questa dovrebbe essere una breve descrizione della funzione che appare nei display tabulari.

Il programmatore può seguirlo con una descrizione più accurata contrassegnata con la parola chiave dettagli . Questa descrizione dettagliata fornisce una descrizione più approfondita di ciò che fa la funzione.

Molte parole chiave di Doxygen sono facoltative. In particolare, la parola chiave dettagli viene assunta se si avvia un paragrafo separato dalla descrizione breve da niente più di una riga vuota.

Oltre questo è una linea separata contrassegnata con la parola chiave param per descrivere ogni argomento della funzione. Infine, la parola chiave return descrive il valore restituito dalla funzione.

Quando compilato, il commento Doxygen per getAccounts () potrebbe apparire come segue:

/ ** brief getAccounts - input account dalla tastiera * dettagli Questa funzione legge l'input dalla tastiera. * Per ogni S o C immesso, la funzione crea un nuovo oggetto * Risparmi o Checking account e lo aggiunge all'elenco * di account. Una X termina la voce. Si presume che qualsiasi altro * input sia un deposito (numeri maggiori di * 0) o un prelievo (numeri inferiori a 0). * * lista accList param e l'elenco di oggetti account * creati da getAccounts () * return void * / void getAccounts (list & accList) {

È inoltre possibile aggiungere un commento Doxygen sulla stessa riga. Questo è più spesso usato quando si commentano i membri dei dati. Posiziona il cursore alla fine della riga e seleziona DoxyBlocks → Line Comment o premi Ctrl + Alt + L. Ora inserisci una descrizione del membro dei dati. Il risultato appare come nel seguente esempio preso anche da Budget5:

doppio bilancio; / ** 

Generazione della documentazione Doxygen
Doxygen può generare documentazione in diversi formati, anche se alcuni (come HTML compilato) richiedono ulteriori download. Il formato HTML è particolarmente comodo in quanto non richiede nient'altro che un browser da visualizzare.
Il valore predefinito è HTML, ma se si desidera modificare il formato selezionare DoxyBlocks → Apri preferenze, quindi selezionare la scheda Doxyfile Defaults 2. In questa finestra puoi selezionare tutti i diversi formati che vuoi generare.
Prima di estrarre la documentazione la prima volta, probabilmente vorrai selezionare alcune altre opzioni. Selezionare DoxyBlocks → Apri preferenze, quindi selezionare la scheda Valori predefiniti Doxyfile. Assicurarsi che la casella Estrai tutto sia selezionata. Quindi selezionare la scheda Doxyfile Defaults 2 e selezionare la casella di controllo Class_Diagrams. Ora seleziona la scheda Generale e controlla la casella Esegui HTML dopo la compilazione. Fai clic su OK e il gioco è fatto. (Non sarà necessario ripetere l'operazione poiché le opzioni vengono salvate in un file chiamato doxyfile.)
Seleziona DoxyBlocks → Estrai documentazione per generare e visualizzare la documentazione. Dopo un intervallo abbastanza breve, Doxygen apre il tuo browser preferito con una documentazione simile a quella mostrata nella figura seguente.
Doxygen non è molto intuitivo quando si tratta di errori di input. A volte Doxygen smette di generare documentazione ad un certo punto nella tua fonte per nessuna ovvia ragione.Controlla il doxygen. file di registro contenuto nella stessa directory del file doxy per eventuali errori verificatisi durante l'estrazione.
L'immagine seguente mostra il browser del progetto nella finestra di sinistra che consente all'utente di navigare all'interno della documentazione del progetto. A destra, è stata selezionata la funzione getAccounts () per ottenere una descrizione più dettagliata. La breve descrizione appare sulla prima riga, seguita dalla descrizione dettagliata, i parametri e il valore di ritorno:

La documentazione di classe è altrettanto accurata come mostrato dal seguente frammento di codice.
/ ** class Account * riassume un conto bancario astratto. * dettagli Questa classe astratta incorpora * propertiescommon per entrambi i tipi di account: * Controllo e risparmi. Tuttavia, manca il concetto * withdraw (), che è diverso * tra i due * / class Account {

La documentazione per Account è mostrata qui:

Si noti la descrizione che appare sotto classe account . Questa è la breve descrizione. Fare clic su Altro ti porterà alla descrizione dettagliata. Notare anche la rappresentazione grafica della relazione di ereditarietà tra Account , le sue classi genitore e le sue classi figli.