Doxygen
[18 April 2010]
Per i progetti di grandi dimensioni una buona documentazione è fondamentale, ma anche per quelli più piccoli può far comodo; in ogni caso, è sempre un lavoro istruttivo. Per Lo Re 2 e Media Esami 2 ho usato Doxygen; è un programma da riga di comando (c'è anche come .exe con GUI) per generare la documentazione a partire dal codice opportunamente commentato.
Per esempio:
/** Descrizione breve
*
* Descrizione dettagliata della funzione
*
* @param param1 descrizione del parametro "param1"
* @return descrizione del valore ritornato dalla funzione
* @see altre funzioni correlate a questa
*/
La documentazione può essere creata in vari formati, i principali sono HTML e LaTeX (compilabile come PDF).
Per impostare le preferenze bisogna modificare i tag nel file generato dal comando doxygen -g.
Quindi:
-scrivere il codice mettendo commenti in un formato compatibile
-creare un file di configurazione con: doxygen -g
-editare a piacere il file
-generare la documentazione con: doxygen
Il manuale completo è sul sito: http://www.stack.nl/~dimitri/doxygen/manual.html
Nel file di configurazione è spiegato nel dettaglio lo scopo di ogni tag.
Per esempio usando il tag HTML_STYLESHEET, che permette di impostare un file CSS, lo stile della documentazione di Media Esami 2 e di Lo Re 2 è quello del sito; Doxygen è molto flessibile!
Qualche esempio di documentazioni generate con Doxygen:
programmazione pseudo-recensioni
Mauro
scrive:
Davvero utilissimo, lo uso sempre per i miei progetti. Inoltre se un progetto non è commentato lo si può dare in pasto ugualmente a Doxygen ottenendo una raccolta delle classi con metodi e gerarchie per avere un'idea di come è strutturata l'applicazione. Mi è capitato di attuare questa procedura durante il tirocinio per cercare di capire come funzionava un framework senza dovermi leggere l'intero codice.
Sunday, 18 April 2010 22:14