DOXYGEN: generazione automatica della documentazione

Doxygen è uno strumento per la generazione automatica della documentazione. Chi si occupa di programmazione sa che, oltre a produrre un programma secondo le specifiche del cliente, occorre anche documentare il proprio lavoro e questo ha un peso rilevante: chi, poi, ha utilizzato Java nella  stesura del  codice  ha  certamente utilizzato JavaDoc. Per fare questo lavoro Doxygen introduce il concetto di TAG, particolari commenti inseriti nel codice sorgente: il linguaggio può essere C o anche C++, mentre il file che si ottiene in uscita può arrivare fino ad un vero e proprio manuale in html e in pdf.

INTRODUZIONE

Questo tool  estrae commenti  dal codice sorgente e in maniera automatica genera un file di tipo HTML. Tutto questo va bene se usiamo Java, ma chi di voi ha utilizzato solo Java come strumento di programmazione? Uno sviluppatore di software per sistemi embedded di solito usa C o C++. Esiste qualcosa di analogo per un linguaggio che non sia Java? Una buona risposta in questo senso è Doxygen, un clone di Javadoc compatibile con C e C++. Per fare questo lavoro in Doxygen è introdotto  il concetto di Tag. In questa trattazione verrà illustrato che cos’è un TAG, come utilizzarlo e quali sono i formati che sono generati.

USO DI DOXYGEN

Con Doxygen è possibile generare documentazione in diversi formati da HTML a Latex, da XML al formato RTF. Inoltre, utilizzando tools addizionali, Doxygen può produrre testo in PDF, PostScript, HTML compresso e in Microsoft Word: tutto  questo inserendo nel codice speciali blocchi di testo chiamati “Comment  Blocks”. Doxygen supporta diversi linguaggi di programmazione come C, C++, Java, Objective-C, Python e IDL. Un discreto numero di progetti di alto profilo utilizzano questo tool com’è evidenziato nella tabella 1, riportata a solo scopo informativo. Per avere una lista completa di chi utilizza Doxygen e dove, il sito ufficiale offre tutte le necessarie informazioni.

Tabella 1. Uso di Doxygen in progetti di alto profilo

Tabella 1. Uso di Doxygen in progetti di alto profilo

Per Iniziare

Certamente la prima  cosa è quella di installare il prodotto.  Il sito ufficiale ha una serie di pacchetti d’installazione e, una volta individuato quello adatto alle proprie esigenze, non resta che scaricarlo gratuitamente. Nella tabella 2 sono riportate le distribuzioni disponibili.

Tabella 2. Distribuzioni disponibili

Tabella 2. Distribuzioni disponibili

È disponibile anche il codice sorgente per permettere particolari modifiche o il porting su host non previsti tra quelli rilasciati. Una volta scaricati i files, la procedura d’installazione non è complicata, è disponibile poi una guida allo scopo di aiutare gli eventuali programmatori per ogni  problema  durante la fase di building  e/o installazione. Il processo di  generazione prende le informazioni contenute in un file di configurazione, chiamato Doxyfile. Questo file è ricavato in automatico con il comando:

doxygen –g filename

Doxyfile, deve poi essere modificato in base alle singole esigenze. Esiste un’altra possibilità per ottenere questo file  ricorrendo  a doxywizard. Questo è un altro tool compreso nel set di fornitura e utilizza un’interfaccia grafica per la creazione e la modifica del file di configurazione. Uno dei meriti più rilevanti di Doxygen è la possibilità di ottenere binari per altre architetture,  in  questo caso se si vuole avere doxywizard allora è necessario durante la compilazione  inserire il  flag  –with-doxywizard: questo abilita l’uso del tool.

File di Output

Doxygen genera, come già visto, file in diversi formati; alcuni sono ottenuti direttamente da Doxygen e altri, per compiere con successo il lavoro di generazione, sono generati indirettamente. Direttamente Doxygen genera i formati:

  • HTML
    È   generato  se GENERATE_HTML  nel  Doxyfile è posto a YES.
  • LATEX
    È generato se GENERATE_LATEX è posto a YES.
  • Man pages
    È generato se GENERATE_MAN  è posto a YES.
  • RTF
    È generato se GENERATE_RTF è posto a YES. Attualmente in RTF esiste una limitazione: infatti, il tool  lavora perfettamente  solo con la versione di Microsoft Word 97.
  • XML
    È generato se GENERATE_XML  è posto a YES. Questa opzione è attualmente ancora sotto sviluppo.

Indirettamente, invece, Doxygen genera i formati compressed HTML, PostScript e PDF. Compressed HTML è utilizzato, per esempio, per i file di help (come in windows 98). Il tool utilizzato per questo processo di traduzione è il Microsoft HTML Help workshop e se, in  doxyfile, GENERATE_HTMLHELP  è posto a YES. Per avere il formato PostScript si utilizza il tool LATEX. Il comando make ps deve essere invocato nella cartella di output. Per un migliore risultato è necessario mettere a NO la variabile PDF_HYPERLINKS. Anche il formato PDF è ottenuto  con LATEX utilizzando il comando make pdf, se vogliamo ottenere un  testo  con  riferimenti   ipertestuali,  allora  il campo PDF_HYPERLINKS dovrà essere messo a YES in doxyfile.

Comment blocks

I comment  blocks rappresentano il perno su cui si regge tutto il processo di traduzione. Doxygen ricava le informazioni su come costruire il documento dalla semantica del programma sorgente e da commenti  speciali che sono stati inseriti nel codice. Questi commenti  speciali sono chiamati “Comment  Block”: se poi  aggiungiamo  dei TAG il Comment Block prende il nome di “Special Documentation Block”. Il Comment Block, che utilizza un formato di tipo C o C++, può avere diversi formati:

  • È  possibile usare uno stile JavaDoc inserendo un doppio asterisco in un commento multi-linea:

1 /**
2 * … questo è un commento
3 */

  • È anche possibile usare una notazione Qt e aggiungere un punto  esclamativo dopo l’apertura di un commento secondo lo stile C, come:

1 /*!
2 * … questo è un commento
3 */

  • Nei due casi l’asterisco in posizione intermedia è opzionale:

1 /*!
2 … questo è un commento
3 */

  • Una terza alternativa è di  utilizzare la seguente notazione:

1 ///
2 /// … questo è un commento
3 ///

  • Oppure:

1 //!
2 //! … questo è un commento
3 //!

  • Alcuni invece preferiscono inserire i loro commenti nel seguente modo:

1 ////////////////////////////////
2 /// … questo è un commento
3 ////////////////////////////////

Il significato di “TAG”

Il TAG è un comando speciale ed è inserito nel codice sorgente anteponendoci un carattere identificativo.  I TAG inseriti nel codice iniziano con un backslah (\) o con il segno @. Alcuni comandi, poi, possono avere uno o più argomenti e l’intervallo di un argomento può essere così rappresentato:

  • Se  l’argomento   è  rappresentato  come  <argomento> allora il campo argomento è una singola parola.
  • Se, invece, è utilizzata la notazione (argomento), allora il campo argomento viene esteso fino alla fine della linea sul quale si trova il commento.
  • Usando la notazione {argomento} allora il campo argomento viene esteso fino al prossimo paragrafo. I paragrafi sono delimitati da una linea bianca o da un indicatore di sezione.
  • Se  troviamo  nella  manualistica l’argomento   in questo formato [argomento] questo  indica che l’argomento stesso è opzionale.

Il listato 1 mostra l’uso dei TAG. Il primo commento usa quattro tag:

  • @brief description, questo tag fornisce una breve descrizione che sarà inserita nel file d’uscita, in questo caso la descrizione può  riferirsi ad un commento generale sulla funzione.
  • @author name1, con questo tag nel file d’uscita ci sarà la stampa del nome dell’autore: name1, nel seguente modo:
    Author:
                  name1
  • @version  VersionNumber,  com’è  intuibile questo tag stamperà nel file d’uscita il numero della versione:
    Version:
                  Version number()
  • @file filename, questo tag stamperà nel file d’uscita il nome del file come header della pagina.

Ci sono altri tag interessanti che possono essere utilizzati, per esempio:

  • @warning per  eventuali  messaggi di  Warning, produce un output del tipo:
    Warning:
                  Messaggio di Warning
  • @bug per una eventuale descrizione dei bachi, produce un output del tipo:
    Bug:
               Descrizione dei Bug
  • @return   variableA, produce  un  output  del tipo:
    Returns:
                    Descrive il ritorno di funzione “variableA”
  • @see FunctionA(), produce un output del tipo:
    See also:
                 FunctionA()
  • @param variableA DescriptionA, produce un output del tipo:
    Parameters:
                  variableA DescriptionA
  • @htmlonly - @endhtmlonly
    Usa <…>
                direttamente  codice html
/**
 * @file
 * @brief Qui scrivere una descrizione del file
 * @brief … segue
 * @author Sono io?
 * @version 1.0
 */

/// Single line comment for Doxygen.

/**
   Write description of function here.
   The function should follow these
   comments.

   The function arguments listed with “param” will be compared
   to the declaration and verified.

   @param argOne Description of first function argument.
   @param argTwo Description of second function argument.
   @return Description of returned value.
*/

int
class::function(arg1, arg2)
{
       /// Single line comment for Doxygen.
}
Listato 1

Sul sito ufficiale si può trovare la lista completa dei TAG disponibili in ambiente Doxygen. I tag possono essere messi in una funzione C++, classe o variabile; inoltre i commenti  messi dopo un’istruzione C++ possono essere contraddistinti  con il tag “”/**< ... */”,  nel seguente modo:

/** Comments on C++ function
...
...
*/
void classA::function_1{
...
int variable1 /**< I commenti
sono messi in questo punto. */
float variable2 /**< I commenti
sono messi in questo punto. */
...

L’uso del TAG @brief non è necessario quando JAVA- DOC_AUTOBRIEF è posto a YES.

Esecuzione di Doxygen

Per procedere alla generazione della documentazione è necessario usare il comando con il file di configurazione associato al progetto  (il  doxyfile deve essere stato creato e modificato in precedenza), in questo modo:

Doxygen project_name.cfg

A questo punto  con Doxygen si ottiene  la docu- mentazione con tutti  i suoi file associati nella car- tella come deciso nel configuration  file (“OUT- PUT_DIRECTORY”).

Conclusione

A prima vista Doxygen può apparire simile ad altri tool come Javadoc o Qt-Doc, ma fornisce certamente delle caratteristiche che danno a Doxygen una marcia in più:

  • portabilità. Esistono, infatti, distribuzioni per Unix, Windows e Mac;
  • compatibilità con JavaDoc, Qt-Doc;
  • il tool è in grado di generare diagrammi per meglio illustrare le dipendenze e il suo codice sorgente;
  • può generare nel formato d’uscita annotazioni sintattiche del codice sorgente in una forma evidenziata;
  • dispone anche di un’interfaccia verso Graphviz per generare un diagramma per C++ con un Graphviz “dot file”;
  • Doxygen può generare anche formule matematiche basate su Latex in un file HTML;

Un altro aspetto da non sottovalutare è che Doxygen è distribuito  secondo i termini  della GNU General Public License.

 

 

Scarica subito una copia gratis

2 Commenti

  1. Avatar photo Giovanni Di Maria 4 Novembre 2016
  2. Avatar photo Maurizio 4 Novembre 2016

Scrivi un commento

Seguici anche sul tuo Social Network preferito!

Send this to a friend