Doxygen
# Doxygen

Doxygen è una applicazione per la generazione automatica della documentazione a partire dal codice sorgente di un generico software. È un progetto open source disponibile sotto licenza GPL, scritto per la maggior parte da Dimitri van Heesch a partire dal 1997.

Doxygen è un sistema multipiattaforma (Windows, Mac OS, Linux, ecc.) ed opera con i linguaggi C++, C, Java, Objective C, Python, IDL (versioni CORBA e Microsoft), Fortran, PHP, C#, e D. Nell'ambito del C++, è compatibile con le estensioni Qt.

È il sistema di documentazione di gran lunga più utilizzato nei grandi progetti open source in C++. Due esempi per tutti, sono l'adozione di doxygen da parte di ACE e KDE. In Java invece, la posizione leader viene meno, in virtù della presenza del concorrente Javadoc.

Il sistema estrae la documentazione dai commenti inseriti nel codice sorgente e dalla dichiarazione delle strutture dati.

## La documentazione prodotta

Il risultato finale è disponibile sotto forma di pagine HTML oppure nei formati CHM, RTF, PDF, LaTeX, PostScript o man pages di Unix. Il formato HTML prodotto si giova di un sistema di hyperlink molto curato che permette al lettore un'agevole navigazione della struttura dei file sorgenti. La documentazione prodotta riporta anche il diagramma delle classi, nei casi in cui sono presenti relazioni di ereditarietà tra strutture dati. Grazie all'impiego sinergico di Doxygen con Graphviz, è possibile includere nella documentazione diagrammi delle classi per tutti gli altri tipi di relazioni tra strutture dati. I documenti possono essere generati in diverse lingue, tra cui è compreso l'italiano.

Infine, il sistema è altamente e facilmente configurabile al fine di permettere all'utilizzatore di intervenire su tutti gli aspetti della documentazione prodotta.

## Il formato dei commenti

Il funzionamento di Doxygen richiede una particolare formattazione dei commenti inseriti nel codice sorgente. Le regole di formattazione, oltre ad essere analoghe a quelle degli altri prodotti della categoria, sono chiaramente documentate nel manuale. Riportiamo di seguito un esempio.

## Il file di configurazione

Doxygen associa ad ogni progetto da documentare un file di configurazione che contiene le impostazioni da utilizzare per la generazione. Questo file è un elenco di assegnazioni di opportuni valori a determinati parametri (TAG). Ogni tag è formato dalla coppia di informazioni

NOME_PARAMETRO = VALORE_PARAMETRO

analogamente a quanto avviene nei file di configurazione di numerosi altri prodotti open source. Un frammento di un esempio del file di configurazione è il seguente:

Come si vede, attraverso il file di configurazione, l'utente stabilisce:

* Il nome del progetto
* la directory dove verrà generato il materiale (directory di destinazione)
* la lingua della documentazione prodotta
* la directory dove si trovano i file sorgente da documentare (directory di origine)
* l'estensione dei file di input da considerare come origine
* l'indicazione di ricorsività nella directory di origine
* l'indicazione di generazione del formato HTML
* nome della directory di destinazione per il formato HTML
* l'indicazione di generazione del formato LaTeX
* nome della directory di destinazione per il formato LaTeX

Doxygen è in grado di generare un file di configurazione generico con il comando

doxygen -g <config-file>

il file generato automaticamente da doxygen contiene dei parametri generici che l'utente può personalizzare o lasciare invariati.

## Utilizzo

Dopo aver installato Doxygen ed aver generato ed eventualmente modificato il file di configurazione, si può invocare l'esecuzione di Doxygen con il comando

doxygen <config-file>

al termine della elaborazione, il materiale prodotto sarà disponibile nella directory di destinazione indicata nel file di configurazione.

