Seguendo il corso di Laboratorio di programmazione sono venuto a conoscenza di Doxygen, uno strumento molto valido(secondo me) per la generazione automatica della documentazione di un sorgente adeguatamente commentato.
Il concetto alla base dello strumento è di riutilizzare i commenti presenti nel codice per generare automaticamente una parte della documentazione.
Si utilizza una particolare sintassi per i commenti in formato doxygen:
/**
*Questo è un commento!
*/
Per utilizzare doxygen bisogna eseguire una serie di operazioni:
-creare un file di configurazione e personalizzarlo opportunamente;
-commentare i propri sorgenti(adeguatamente!);
-eseguire doxygen in modo che la documentazione venga generata.
La sintassi per creare un nuovo file di configurazione tramite la shell di linux, (o cigwin) è:
doxigen -g < nome_file_configurazione>
A questo punto con un editor passiamo alla personalizzazione del file.
Una volta ultimate le modifiche su file di configurazione, per produrre
la documentazione lanceremo il comando:
doxygen < nome_file_configurazione>
La documentazione è stata creata!!!
Doxygen da la possibilità di creare una pagina html con immagini, link ad altre pagine; molto valido ad esempio per poter includere in essa oltre che la documentazione "base" del programma, una vera e propria relazione ottimamente strutturata.
I comandi da utilizzare per impostare la documentazione sono
qui.
Qui potrete trovare tutto su questo strumento:
http://www.doxygen.org