I primi comandi

Per documentare i nostri programmi non dovremo far altro che inserire nel codice dei commenti utilizzando una formattazione particolare che Doxygen è in grado di interpretare. Doxygen può estrarre moltissime informazioni autonomamente anche da codice non documentato ma utilizzando particolari accorgimenti saremo in grado di sfruttarne tutte le potenzialità. Vediamo un primo esempio in C++:

Vedi la documentazione generata

Come si vede dall'esempio la sintassi è estremamente semplice. Prima di tutto bisogna notare che Doxygen estrae la sua documentazione solo da commenti che cominciano con "//!" o "/*!" o "/**", per linguaggi come C, C++ e Java. Nel caso di Python invece i commenti devono cominciare con "##". Tutti gli altri commenti sono ignorati.

Per commentare particolari entità all'interno dei nostri programmi utilizziamo delle parole chiave, o comandi, che Doxygen utilizza per strutturare la documentazione. Ad esempio il comando "\brief" indica che quello che segue è una descrizione breve della classe o funzione che stiamo documentando. Solitamente dopo una descrizione breve troviamo una descrizione più dettagliata. Si noti il modo in cui nell'esempio vengono divisi i due tipi di descrizione.

Un'altro comando che troviamo nell'esempio è "\param", utilizzato per documentare un parametro di una funzione. Esso è seguito dal nome del parametro e dalla relativa descrizione. Similmente "\return" documenta il valore di ritorno di una funzione. Si noti anche l'uso del comando "\n" per andare a capo.