Configurare il Doxyfile

Abbiamo già avuto modo di creare un Doxyfile base e di effettuare le prime modifiche. Ma essendo un programma estremamente potente e versatile Doxygen ci mette a disposizione una miriade di opzioni tra le quali a volte non è facilissimo orientarsi, specialmente per chi effettua i primi passi. Oltre alle già menzionate "INPUT", "OUTPUT_DIRECTORY", "PROJECT_NAME" e "PROJECT_NUMBER" sono di particolare utilità le seguenti voci:

• FILE_PATTERNS - Se non vogliamo specificare i file uno per uno possiamo ricorrere all'utilizzo di "wildcard" come "*.cpp", "*.h", "*.java" etc.

• RECURSIVE - Impostandolo a "YES" Doxygen cercherà i file di input anche nelle sotto directory. 

• IMAGE_PATH - Specifica la o le directory in cui Doxygen cerca le immagini inserite nella documentazione utilizzando il tag "\image".

• GENERATE_TREEVIEW - Impostandolo su "YES" Doxygen genererà anche una vista ad albero ("treeview") della documentazione.

• EXTRACT_ALL - Impostandolo su "YES" Doxygen estrarrà documentazione anche dalle classi non documentate. Molto utile se vogliamo studiare la struttura di un progetto poco o non documentato.

• SOURCE_BROWSER - Impostando a "YES" questa opzione Doxygen genererà una lista di file sorgenti consultabili direttamente all'interno della documentazione, con tanto di link incrociati tra le varie entità (classi, funzioni etc.) e le rispettive pagine di documentazione.

• INLINE_SOURCES - Impostando questa voce a "YES" Doxygen includerà nel corpo di classi e funzioni i rispettivi sorgenti.

• STRIP_CODE_COMMENTS - Impostandolo a "YES" Doxygen non mostrerà nella documentazione i commenti ordinari (non-Doxygen) presenti nei sorgenti. Nota che i blocchi di commenti Doxygen non vengono comunque mai mostrati.

• ALPHABETICAL_INDEX - Impostandolo a "YES" Doxygen inserirà nella documentazione un indice alfabetico di tutte le entità. Se il tuo progetto contiene numerose classi, funzioni, strutture etc. è altamente consigliato attivare questa opzione.

• IGNORE_PREFIX - Se le classi del tuo progetto cominciano con uno specifico prefisso come la "Q" di "QWidget" in Qt o "wx" di "wxWindow" in wxWidget o "C" in "CWindow" in MFC pui utilizzare questa opzione per specificare i prefissi che Doxygen deve ignorare durante la costruzione dell'indice alfabetico.

• GENERATE_HTML - Impostalo a "YES" se vuoi generare documentazione HTML.

• GENERATE_LATEX - Impostalo a "YES" se vuoi generare documentazione LaTeX.

• INTERNAL_DOCS - Impostalo a "YES" se vuoi che la documentazione includa i blocchi marcati come "interni" attraverso l'uso del comando "\internal".

• JAVADOC_AUTOBRIEF - Quando questa opzione è impostata a "YES" Doxygen interpreta la prima linea (fino al primo punto) di un commento in stile JavaDoc come la descrizione breve di un'entità (quindi non c'è bisogno di "\brief"). Nota che questo funziona solo per commenti in stile JavaDoc, ovvero quelli che cominciano con "/**".

Ci sono moltissime altre opzioni presenti nel Doxyfile. Per conoscerle la cosa migliore è consultare i commenti presenti nel Doxyfile e provare con mano i vari settaggi. Se preferite è anche possibile editare il Doxyfile usando Doxywizard. Si noti però che tale programma cancellerà i commenti dal vostro Doxyfile, cosa che renderà più difficile editarlo manualmente in seguito.