Tesi di Laurea Triennale in

Ingegneria del Software

Anno accademico 2015/2016

Linguaggi e strumenti per la generazione

di documentazione del codice sorgente

Studente: Stefano Ciardulli

Docente: Por�rio Tramontana

1

Indice

1 La documentazione del codice software 3

1.1 Primi approcci alla documentazione . . . . . . . . . . . . . . . . 3

2 Javadoc 6

2.1 Introduzione a Javadoc . . . . . . . . . . . . . . . . . . . . . . . . 62.2 Tags Javadoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 Doxygen 10

3.1 Installare Doxygen . . . . . . . . . . . . . . . . . . . . . . . . . . 113.2 Documentare il codice . . . . . . . . . . . . . . . . . . . . . . . . 133.3 Produrre la documentazione . . . . . . . . . . . . . . . . . . . . . 15

4 Altri strumenti di documentazione 17

4.1 ROBODoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.2 NaturalDocs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224.3 HeaderDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244.4 PHPDoc e phpDocumentor . . . . . . . . . . . . . . . . . . . . . 244.5 Quale strumento utilizzare? . . . . . . . . . . . . . . . . . . . . . 264.6 Tabelle riepilogative . . . . . . . . . . . . . . . . . . . . . . . . . 28

2

Capitolo 1

La documentazione del codice

software

1.1 Primi approcci alla documentazione

L'importanza di processi e standard che diano supporto al programmatore nelladocumentazione del codice di un prodotto software è stata messa in rilievo giànei primi anni ottanta. Il primo ad evidenziare la mancanza di una adegua-ta documentazione nei prodotti software fu Scott L. McGregor, il quale stilò,per conto della Hewlett-Packard, un rapporto sulle procedure di documentazio-ne di diversi progetti sviluppati in quegli anni dai ricercatori dell'università diCarnegie-Mellon. In tale rapporto McGregor evidenzia come i problemi princi-pali che si riscontrano nel creare una documentazione completa e coerente sonoessenzialmente tre:

• forte disapprovazione degli addetti ai lavori a documentare il codice conoperazione tediose e ripetitive da e�ettuare manualmente;

• mancanza di uno standard in grado di delineare le linee guida da seguirenella generazione della documentazione;

• di�coltà nel renderla comprensibile a qualsiasi livello di programmazione.

Risulta quindi chiara l'esigenza di creare programmi automatici e standardche aiutino e supportino il programmatore nella creazione di un'adeguata docu-mentazione, sempre più necessaria man mano che il numero di righe di codicedi un progetto software andava aumentando.

In passato ci furono diversi esempi di generatori automatici di documen-tazione. Uno di questi è il Documentation Support System sviluppato dallaGeneral Elettric. Il Documentation Support System utilizza uno pseudo-codice,chiamato PDL (�gura 1.1), basato sulla combinazione tra frasi in inglese e co-struzioni logiche, IF-ELSE-END IF. L'utilizzo di questo standard riusciva a da

3

Figura 1.1: esempio di template PDL

rendere il codice sorgente più leggibile e supportato da una valida documenta-zione. Tuttavia, costringeva ancora il programmatore a inserire manualmentemolte informazioni.

Il problema risiedeva nella mancanza di un framework valido su cui de�ni-re un design strutturato per l'implementazione di un algoritmo dedicato allagenerazione automatica della documentazione del codice sorgente.

Nei laboratori NASA fu a�rontato questo problema e venne sviluppato RN-DOC che proponeva un sistema di documentazione automatica su programmiscritti in Fortran basato su interfacce d'interazione grazie alle quali era possi-bile commentare tutte le componenti chiave del codice. RNDOC è un parserche decompone il codice sorgente del programma dato in input identi�cando imoduli e i simboli di cui è composto. L'utente ha così la possibilità di applicarei commenti con l'ausilio di opportune interazioni di inserimento e salvare in unnuovo �le il codice opportunamente commentato

4

Un altro studio interessante, sull'automatizzazione della documentazione dicodice software, venne presentato ad una conferenza tenutasi a Città del Messiconel 1984. In questa occasione venne presentato un sistema che doveva servire adocumentare i programmi software scritti, in linguaggio Cobol, per il ministerodel Bilancio Messicano. L'architettura di questo sistema era composta da tremoduli: dictionary module, program documentation processor module, �le de-scription module.Il dictionary module crea una corrispondenza biunivoca tra tutte le parole chia-vi del Cobol e un equivalente pseudo linguaggio Spanish-Cobol dedicato alladocumentazione.Il program documentation processor module analizza il codice sorgente dato ininput e in base al dictionary de�nito genera la documentazione vera e propria.Il �le description module scrive su un �le apposito la documentazione ricevutadal program documentation processor, applicando una formattazione adeguataalla lettura dell'utente.

Tuttavia, sebbene i molteplici sforzi impiegati dalle grandi società pubbli-che e private per rendere l'attività di documentazione di un prodotto softwaresempre più a�dabile e precisa, mancava ancora uno standard comune in gradodi garantire un'universale compatibilità d'uso. Il primo che provò a de�nireuno standard universale fù Enrique Arce Medina. Enrique Medina a�ermavache la documentazione interna di un software doveva essere completa, sintetica,priva di ambiguità e ben organizzata. Ad ogni procedura doveva essere de�-nita un'intestazione, tramite commenti, con lo scopo di riassumere brevementee schematicamente tutte le sue caratteristiche. L'utente avrebbe potuto cosicomprendere tutte le funzionalità della procedura semplicemente leggendo lesemplici sezioni di commenti ben formati, senza dover analizzare l'intero codice.L'intestazione doveva descrivere i seguenti tipi d'informazione:

• nome procedura;

• nome dell'autore e data in cui è stata realizzata;

• sintetica descrizione della funzionalità;

• tipo di strategia algoritmica utilizzata;

• lista degli argomenti con relativo ruolo;

• eventuali vincoli di utilizzo;

• elenco delle condizioni di errore;

• elenco delle sub-routine che utilizza;

• formato dei dati in input e degli eventuali risultati restituiti.

L'intestazione inoltre potrebbe essere ulteriormente arricchita con addizio-nali informazioni come l'elenco delle dimensioni delle locazioni di memoria peri dati temporanei o uno schematico esempio d'uso. Medina consigliava anchel'uso di un'opportuna intentazione del codice, al �ne di migliorarne la leggibilità.

5

Capitolo 2

Javadoc

2.1 Introduzione a Javadoc

Il primo passo concreto per la realizzazione di un programma in grado di gene-rare automaticamente documentazione di codice software è stato fatto nel 1994.É in quest'anno infatti che viene distribuito un applicativo chiamato Javadoc,realizzato dai ricercatori della Sun Microsystem mentre stavano lavorando allosviluppo del linguaggio Java e delle sue librerie. Tale applicativo fornisce mec-canismi per la generazione automatica di documentazione in formato HTML.L'utilizzo di Javadoc permette di documentare i sorgenti di un programma al-l'interno dei sorgenti stessi, evitando così la creazione di �le separati. Per do-cumentare il codice sorgente dobbiamo scrivere dei blocchi di commento, docu-mentation comments, delimitati dai caratteri /∗∗ e ∗/ al cui interno inseriamo leinformazioni desiderate, che possono essere costituite da semplice testo, da tagHTML e da tag speciali riconosciuti solo da Javadoc. Tali blocchi di commentosono inseriti nel codice sorgente. Successivamente Java, tramite il compilatore,estrae la documentazione dal codice basandosi su alcune regole di sintassi.

Un commento Javadoc viene inserito immediatamente prima della dichiara-zioni di:

• classi;

• interfacce;

• metodi;

• attributi;

• ...

Più in generale tutto ciò che si vuole rendere chiaro a chi avrà a che fare conil codice o semplicemente a chi leggerà la documentazione.

6

2.2 Tags Javadoc

Buona norma è dividere il commento Javadoc in due parti: una prima descri-zione in linguaggio naturale di ciò che si sta andando a sviluppare e i diversitags, che possono essere tag HTML o tag speci�ci di java, block tags.

I block tags sono etichette standard, opzionali, precedute dal carattere '@'che identi�cano le componenti dell'oggetto che si sta commentando.

Block tags comuni sono:

1. @author: utilizzato per speci�care il nome dell'autore.Se ci sono più autori è possibile utilizzare più tag '@author' o più sempli-cemente far seguire al tag i diversi nomi separati dalla virgola.@author autore, altroautore

2. @version: indica la versione del programma;

3. @param: seguito dal nome del parametro, utile per la descrizione diciascun parametro. Un tag per ogni parametro;

4. @returns: speci�ca il valore ritornato dal metodo considerato;

5. @exception: seguito dal nome dell'eccezione, descrive le circostanze chedeterminano il lancio dell'eccezione;

6. @see: rimanda a un'altra voce di documentazione;

Altri tags utilizzabili per documentare il codice sorgente sono:

• @deprecated: consente di indicare che un elemento è deprecato e il suoutilizzo è scoraggiato poiché, per esempio, il medesimo è stato sostituitocon uno più recente;

• @since: consente di indicare che un elemento è già presente da unadeterminata versione;

• @value: consente di far visualizzare il valore di un dato membro costante;

• @inheritDoc: consente di ereditare la documentazione già scritta per unmetodo, quando lo stesso è stato sovrascritto.

Una volta scritta tutta la documentazione della classe in oggetto, se si stalavorando con eclipse, è su�ciente cliccare su 'Generate Javadoc...' presentenella scheda 'Project' per generare il �le html con tutte le informazioni relativealla classe considerata.

7

Esempio di commento scritto seguendo le regole di javadoc:

8

Relativo output html:

9

Capitolo 3

Doxygen

Doxygen è il sistema di documentazione di gran lunga più utilizzato nei grandiprogetti open source in C + +. Tuttavia esso opera con la maggior parte deilinguaggi di programmazione come: Java, C, Python, Fortran e PHP.

Doxygen supporta lo sviluppatore in tre modi:

1. permette di creare una documentazione in formato HTML navigabile on-line oltre che un manuale di riferimento o�ine, creati a partire da uninsieme di �le sorgenti commentati. Doxygen inoltre permette la genera-zione di output in formato RTF(MS-Word), PostScript , PDF e pagineman di Unix;

2. permette di estrarre la struttura del codice anche da �le sorgenti non docu-mentati. Rende quindi possibile visualizzare le relazioni tra i vari elementidel progetto mediante gra�ci di dipendenza, diagrammi di successione ediagrammi di collaborazione, che sono tutti generati automaticamente;

3. è possibile inoltre utilizzare Doxygen per creare una normale documenta-zione del codice.

Per generare un manuale con Doxygen bisogna preliminarmente documen-tare il codice sorgente con blocchi speciali di documentazione e successivamentegenerare un �le di con�gurazione tramite Doxygen con il comando: 'doxygen -g<con�g_�le>'. Nel �le di con�gurazione è possibile speci�care i �le di input ealtre informazioni aggiuntive.

10

Qualora avessimo generato un �le di con�gurazione con una vecchia versionedi Doxygen è possibile e�ettuarne l'upgrade alla versione più recente con ilcomando: 'doxygen -u <con�g_�le>'. In questo modo tutte le impostazioni nel�le di con�gurazione originale saranno copiate nel nuovo �le di con�gurazione,eventuali nuove opzioni avranno il loro valore di default.

3.1 Installare Doxygen

I metodi per installare Doxygen ovviamente cambiano in base al sistema opera-tivo utilizzato.

L'installazione del prodotto sulla piattaforma Windows è molto semplice, inquanto Doxygen viene rilasciato come un archivio auto-installante. É quindisu�ciente seguire le �nestre di dialogo.Dopo l'installazione è consigliato scaricare e installare il pacchetto GraphVizche permette di migliorare il design dei diagrammi prodotti da Doxygen. Pergenerare la documentazione in HTML è inoltre necessario disporre di Microsoft

HTML Help Workshop scaricabile gratuitamente dal sito di Microsoft. Se sivuole produrre �le Qt è invece necessario qhelpgenerator che fa parte di Qt,scaricabile, anch'esso gratuitamente, da www.qt.io . Inoltre, al �ne di generareoutput PDF o utilizzare formule scienti�che, viene utilizzato LATEX. Le versionidi LATEXcompatibili con Doxygen sono MikTex e proTeXt.

11

La �gura seguente mostra la relazione tra gli strumenti di Doxygen e il �ussodi informazioni tra di essi:

12

3.2 Documentare il codice

I commenti relativi a un'entità del programma possono essere brevi, in ge-nere sviluppati su una sola riga, o possono consistere in una più dettagliatadescrizione dell'entità, e quindi diventare veri e proprio 'blocchi' di commenti.

Per racchiudere blocchi di commenti è possibile procedere in diversi modi:

1. secondo lo stile javadoc. Come detto in precedenza il blocco inizia colcarattere '/**' e termina con '*/' mentre ogni riga è preceduta da unasterisco;

2. utilizzare lo stile Qt secondo un blocco di commento si apre con i caratteri'/*!' e si chiude con i caratteri '*/';

I commenti brevi sono sviluppati su poche righe e quindi solitamente nonvengono racchiusi in un blocco ma basta anteporre i caratteri '///' oppure '//!'all'inizio di ogni riga. Qualora si volesse racchiudere un commento breve in unblocco è possibile utilizzare il comando \brief. Tale comando termina con unariga vuota.

Le descrizioni brevi sono incluse nella panoramica dell'entità che si sta do-cumentando e vengono stampate utilizzando il corsivo. Doxygen fornisce quindiun meccanismo per de�nire esplicitamente ciò che fa parte della panoramicadell'entità e ciò che invece viene documentato più in dettaglio. Questo mecca-nismo non è presente in Javadoc dove, per impostazione prede�nita, la primafrase del blocco documentazione è trattato automaticamente come una descri-zione breve. Tuttavia è possibile abilitare questo comportamento impostandoJAVADOC_AUTOBRIEF su YES nel �le di con�gurazione.

A di�erenza di molti altri sistemi di documentazione, Doxygen consenteanche di porre la documentazione dei membri prima della loro de�nizione. Inquesto modo la documentazione può essere scritta direttamente nel �le sorgenteanziché nell' header �le. Questo rende l'header �le più compatto e permette allosviluppatore un accesso più diretto alla documentazione. Come compromessola descrizione breve dovrebbe essere collocata prima della dichiarazione e ladescrizione dettagliata prima della de�nizione utente.In determinati casi si desidera commentare i membri di una struct o di unaclasse dopo il membro stesso e non prima. A tal �ne è su�ciente utilizzare ilmarcatore < nel blocco di commento. Si noti che tale marcatore può essereutilizzato anche per i parametri di una funzione.

13

In generale Doxygen permette di piazzare la documentazione in qualsiasiparte del progetto si desideri, ad eccezione del corpo di una funzione. Perpoter sfruttare tale 'libertà' è necessario utilizzare dei comandi strutturali cheindichino l'elemento che si vuole commentare. I comandi strutturali vengonopreceduti dal carattere \, oppure @ qualora si stia utilizzando lo stile javadoc,e seguiti dal nome dell'elemento.Alcuni di questi comandi sono:

• \class class_name, per documentare la classe class_name;

• \struct struct_name, per documentare la struct struct_name;

• \�le �le_name, per documentare il �le �le_name;

• \fn fn_name, per documentare la function fn_name;

• \var var_name, per documentare la variabile var_name;

• \package package_name, per documentare il package java package_name;

14

3.3 Produrre la documentazione

Per generare il manuale del nostro progetto con Doxygen, dopo aver commentatolo stesso secondo la sintassi scelta, è necessario seguire alcuni passaggi:

1. generare il �le di con�gurazione chiamando doxygen con l'opzione -g;

2. modi�care il �le di con�gurazione in modo che corrisponda col progettoin questione;

3. generare la documentazione, in base a come è stato impostato il �le dicon�gurazione, con il comando doxygen < config_file >.

Un �le di con�gurazione doxygen è un �le di testo con nome prede�nitoDoxy�le. Tale �le consiste in un elenco di assegnazioni di opportuni valori adeterminati parametri, tag. Ogni tag è formato dalla coppia di informazio-ni: NOME_PARAMETRO = V ALORE_PARAMETRO. Se lo stesso tagviene de�nito più di una volta resta valida l'ultima de�nizione. Per i tag chede�niscono una lista di argomenti l'operatore + = può essere usato al posto di= per aggiungere nuovi valori all'elenco. Se il valore contiene uno o più spazideve essere racchiuso tra doppi apici.

I tag di con�gurazione possono essere divisi in diverse categorie.I tag più comuni relativi al progetto sono:

• PROJECT_NAME = �NOME PROGETTO�, il valore di default è MyProject;

• OUTPUT_DIRECTORY = doc, tale comando serve a speci�care la direc-tory di output. Di default doxygen genera tutto nella directory corrente;

• GENERATE_LATEX = NO, utile qualora si voglia inibire la generazionedi un manuale in formato latex;

• OUTPUT_LANGUAGE = italian, setta la lingua italiana;

• INLINE_INHERITED_MEMB se settato con YES doxygen mostreràtutti i membri ereditati dalla classe che si sta documentando;

• OPTIMIZE_OUTPUT_FOR_C tale tag è utile settarlo qualora il pro-getto si compone di solo sorgente C, al �ne di ottimizzare il processo digenerazione di documentazione. Tag simili sono presenti per Java, Fortrane VHDL;

• TAB_SIZE, tale tag può essere utilizzato per settare il numero di spazipresenti in un tab;

• SEPARATE_MEMBER_PAGES se settato su YES doxygen produrràuna nuova pagina per ogni membro documentato altrimenti la documen-tazione di un membro sarà parte del �le/classe/namespace che lo contiene.

15

Tag relativi alla costruzione della documentazione sono:

• EXTRACT_ALL, se settato su YES Doxygen estrae la documentazione diogni entità, anche qualora non vi fosse una documentazione disponibile(?),ad eccezione dei membri privati;

• EXTRACT_PRIVATE, settare tale tag su YES indica la volontà di volerincludere nella documentazione anche i membri privati;

• HIDE_UNDOC_MEMBERS, grazie a questo tag possiamo decidere sei membri non documentati devono essere nascosti o visibili dal manualegenerato con Doxygen;

• GENERATE_BUGLIST, può essere utilizzato per abilitare(YES) o disa-bilitare(NO) l'elenco dei bug. Tale elenco può essere creato, all'interno dei�le sorgente, col comando \bug;

• GENERATE_TESTLIST, può essere utilizzato per abilitare(YES) o di-sabilitare(NO) l'elenco dei test. Tale elenco può essere creato, all'internodei �le sorgente, col comando \test;

Opzioni di con�gurazione relative ai warning sono:

• WARN_IF_UNDOCUMENTED, se impostato su YES Doxygen generamessaggi di warning per tutte le entità per le quali non viene trovata larelativa documentazione;

• WARN_IF_DOC_ERROR, se tale tag è attivo Doxygen genera avvi-si per eventuali errori nella documentazione, come la documentare diparametri che non esistono;

• WARN_AS_ERROR, impostandolo su YES Doxygen si blocca quandogenera un warning;

• WARN_LOGFILE, può essere utilizzato per speci�care il �le in cui devo-no essere riportati i messaggi di warning

16

Capitolo 4

Altri strumenti di

documentazione

4.1 ROBODoc

ROBODoc è un tool di documentazione automatica simile al Javadoc distribuitosotto licenza A�ero scritto nel 1995. Esso é in grado di generare la documen-tazione estrapolando le informazioni necessarie da un unico �le in cui oltre alcodice implementativo, è innestato il codice per la documentazione tramite tagcommenti opportunamente modi�cati. Questo facilita le fasi di aggiornamentotra le modi�che del codice sorgente e la relativa documentazione.

ROBODoc possiede una particolarità che lo distingue sensibilmente da tuttigli altri tool di documentazione automatica: può essere applicato a qualsiasilinguaggio che supporti un marcatore di commenti e la sua principale funzioneè quella di estrarre e interpretare le informazioni in esse contenute in base adun template opportunamente de�nito in fase di inizializzazione.

Gli elementi principali di ROBODoc sono gli Headers. Un Header consistedi tre di�erenti elementi:

• marcatore iniziale;

• sequenza di blocchi;

• marcatore �nale.

Il marcatore iniziale fornisce a ROBODoc il nome del componente che sista documentando, il modulo di cui fa parte e il tipo dell'elemento.

∗ ∗ ∗ ∗ f ∗ financial.library/StealMoney

17

In questo esempio, reperito dal manuale u�ciale di ROBODoc, il nome delcomponente che si sta documentando è StealMoney, il modulo di cui fa parteè �nancial.library, mentre con la lettera f indichiamo il tipo dell'elemento chestiamo andando a documentare, ossia una function. ROBODoc si aspetta sem-pre che ci sia una �\� che separi il nome del modulo dal nome dell'elemento.Questo separatore è fondamentale per generare l'indice rispettando la strutturagerarchica dei vari componenti.

Un blocco é composto dal titolo e dal testo del commento vero e proprio.Tutte le linee del blocco sono precedute dal carattere �*�.

Figura 4.1: esempio fornito dal manuale u�ciale di ROBODoc

In questo esempio il nome del blocco è functionIl marcatore �nale è una sequenza di sei asterischi che indicano la �ne del

blocco.ROBODoc de�nisce anche un elenco prede�nito di headertype che possono

essere utilizzati per migliorare l'indicizzazione dei componenti. Gli headertypepossono essere personalizzati per indicizzare anche altri tipi di componenti, comead esempio quelli di un linguaggio di validazione XML. Essi possono inoltreessere usati per l'intitolazione dei blocchi.

Di seguito una tabella, messa a disposizione sull'user manual di ROBODoc,di headertype prede�niti riconosciuti da ROBODoc.

18

Una volta innestati correttamente, all'interno del codice sorgente, i blocchidi commenti secondo le speci�che di cui sopra, ROBODoc è pronto per estrarrela documentazione.

La scelta per il formato d'output per la documentazione è varia. Innanzi-tutto, c'è da dire che le modalità in cui ROBODOc può operare sono tre:

• multidoc;

• singledoc;

• single�le.

In modalità multidoc, ROBODoc analizza tutti i sources �les contenuti al-l'interno della directory dei sorgenti e crea per ciascuno di essi un documentation�le all'interno della directory d'output. Il risultato �nale è una proiezione do-cumentata del codice sorgente. La modalità multidoc è utile per creare unadocumentazione facilmente consultabile tramite un browser.

In modalità singledoc, ROBODoc analizza tutti i sources �les e genera unsingolo documentation �le. Tale modalità viene usata quando si vuole con-segnare al cliente tutta la documentazione in un unico �le. Utile quando sivuole incorporare la documentazione appena prodotta in una documentazionepiù grande già sviluppata.

La modalitá single�le non è la migliore per produrre una leggibile documen-tazione. Essa viene infatti utilizzata per operazioni di debugging.

19

Una volta decisa la modalità con cui ROBODoc andrà a generare la docu-mentazione è possibile sceglierne il formato. Tra i vari formati possibili ci sono:HTML, utile per creare una documentazione consultabile online, RTF, vieneusato quando si vuole creare un documento che andrà incluso in una più vastadocumentazione Word, LATEX per creare documentazione portabile.

Ecco un esempio più completo di documentazione creata con ROBODoc:

Figura 4.2: tipico Header ROBODoc

20

Figura 4.3: relativo output in formato HTML

21

4.2 NaturalDocs

NaturalDocs é un generatore di documentazione sviluppato da Greg Valure.Esso viene distribuito sotto licenza A�ero ed è scritto in Perl.

NaturalDocs è in grado di supportare qualsiasi linguaggio di programmazio-ne che consente l'inserimento di commenti, ma solo sui linguaggi ActionScript2.0, C# e Perl è in grado di analizzare e generare automaticamente la documen-tazione di funzioni, variabili e classi senza la necessità di inserire esplicitamentei commenti manualmente.

NaturalDocs non ha un proprio linguaggio di documentazione. É possibileinserire nel codice blocchi di commenti o singole linee, scritte in diversi linguag-gi(ad esempio JavaDoc). L'unico requisito è che i commenti non siano inseritisulle stesse righe del codice.

La documentazione può essere anche inclusa in un �le di testo a parte. In-fatti, qualsiasi �le con estensione .txt presente nella directory dei sorgenti saràincluso nella documentazione. Esso sarà trattato esattamente come un source

�le, il che signi�ca che apparirà nel menù della documentazione e gli argomen-ti presenti al proprio interno verrano inclusi nell'indice della documentazione.Ovviamente, i commenti inseriti nel �le di testo non hanno bisogno di esserepreceduti da alcun simbolo.I �le di testo con all'interno i commenti vengono utilizzati perlopiù per docu-mentare l'architettura generale del programma, impostazioni di con�gurazioneo qualsiasi cosa che non sia direttamente legata al codice sorgente.

22

Nella documentazione è anche possibile includere immagini. Il comando dautilizzare è see nome_immagine

Il limite più grande di NaturalDocs è che esso fornisce un solo tipo di output,HTML. Probabilmente è per questo motivo che questo strumento non vieneusato molto nell'industria del software, eccezion fatta per gli sviluppatori cheutilizzano ActionScript 2.0 in quanto è l'unico a fornirne un pieno supportoautomatizzato.

23

4.3 HeaderDoc

HeaderDoc è un sistema di generazione automatica di documentazione del codicesorgente sviluppato dalla Apple Inc.

Come i programmi visti sopra anche questo è basato sull'innesto di commen-ti speciali all'interno del codice sorgente dato in input. La sintassi dei commentiin HeaderDoc è simile a quella utilizzata in JavaDoc con la di�erenza che Hea-derDoc dispone di tag più �formali� che permettono un maggiore controllo sulcomportamento della documentazione prodotta da HeaderDoc.

HeaderDoc è destinato principalmente per l'uso su sistemi operativi OS.Tuttavia, in diverse versioni, è stato utilizzato con successo anche su Linuxe Solaris. Esso supporta una vasta gamma di linguaggi di programmazione,tra cui: Objective C/C + +, C/C + +, Java, Javascript, Pascal, Perl, PHP eovviamente AppleScript.

HeaderDoc è composto da due utility: la principale, headerdoc2html, chegenera la documentazione vera e propria e gatherheaderdoc che crea la ta-

ble of contents. Gatherheaderdoc utilizza uno strumento, chiamato resolve-

Links, che permette di creare collegamenti tra i vari �le di documentazione.É possibile utilizzare resolveLinks anche per collegare insieme due o più set didocumentazione.

Questo strumento di generazione automatica di documentazione del codicesorgente è possibile trovarlo già installato e pronto per l'uso sulla maggior par-te dei sistemi operativi Apple. In alternativa è possibile scaricarlo gratuitamentedalla Darwin source collection al link: www.opensource.apple.com/darwinsource/.

I formati di output della documentazione possibili tramite HeaderDoc sonosolamente due: HTML e XML.

4.4 PHPDoc e phpDocumentor

Il PHPDoc è un addatamento di javadoc per il linguaggio di programmazionePHP. PHPDoc è uno standard, ancora in corso di formalizzazione, che de�nisceregole per commentare il codice PHP, con l'intento di o�rire due importantivantaggi:

• incoraggiare i programmatori a documentare aspetti del codice che comu-nemente verrebbero ignorati;

• predisporre la generazione automatica di documentazione ben strutturatae facilmente comprensibile tramite l'uso di parser come PhpDocumentor;

I componenti base del PHPDoc sono:

• DocBlock: commenti in stile javadoc, de�niti dalla struttura �/ ∗ ∗ ∗ /�che precedono l'elemento da documentare;

• Tags: parametri con pre�sso �@� che informano il parser che tipo diinformazioni devono essere elaborate.

PHPDoc supporta codice PHP sia object-oriented che di tipo procedurale.

24

PhpDocumentor è il tool che analizza il codice sorgente integrando le infor-mazioni de�nite da commenti strutturati secondo le speci�che del PHPDoc. Ilformato d'output �nale può essere impostato in HTML, PDF o CHM.

Altre funzionalità interessanti, speci�che di phpDocumentor, sono:

• il supporto per il riferimento incrociato con documentazioni di altri pro-getti o alla documentazione u�ciale del PHP;

• la possibilità di impostare tipi di documentazione dedicati in base al tipodi utente �nale come ad esempio tutorial passo passo personalizzati.

Un esempio di DocBlock

Relativo MarkDown di output:

25

4.5 Quale strumento utilizzare?

Dopo aver visto brevemente gli strumenti maggiormente utilizzati per la gene-razione automatica della documentazione del codice sorgente la domanda sorgespontanea: �Quale tra questi strumenti conviene utilizzare?�. La risposta piùgiusta è �dipende�. Le variabili che dobbiamo prendere in considerazione quan-do andiamo a scegliere lo strumento da utilizzare sono diverse: linguaggio diprogrammazione utilizzato, sistema operativo su cui si sta lavorando, tipo didocumentazione da dover stilare e così via. Cerchiamo quindi di fare un breveriepilogo degli strumenti già visti evidenziandone punti di forza e di debolezza.

• JavaDoc: Il più grande punto di forza di JavaDoc è anche un suo puntodebole, il compilatore Javac. L'utilizzo del compilatore di Java è garanziadi produzione di documentazione il più esatta possibile: l'esempio più si-gni�cativo da questo punto di vista è la creazione, da parte di javac, delcostruttore di default e la sua conseguente presenza nella documentazioneHTML, anche nel caso in cui tale costruttore non venga indicato esplicita-mente dal programmatore nel codice sorgente. Inoltre Javadoc permettedi produrre output nei più disparati formati: HTML, RTF, PDF, Latex,XML. L'utilizzo di javac però indica anche che javadoc può essere sfruttatosolo con riferimento a codice java e non ad altri linguaggi di programma-zione. Per questo motivo è facile capire quando utilizzare javadoc: quandostiamo scrivendo codice java. Infatti Javadoc è lo strumento di produzio-ne della documentazione più a�dabile per Java mentre non è compatibilecon altri linguagi.

• Doxygen: Possiamo dire già da subito che Doxygen o�re più vantaggi chesvantaggi. Innanzitutto doxygen è altamente con�gurabile. Ciò permetteall'utilizzatore di intervenire su quasi tutti gli aspetti della documentazioneprodotta come: directory di destinazione della documentazione prodotta,lingua da utilizzare nella produzione della documentazione e tanti altrisvariati aspetti, di cui è stato fatto un accenno nel capitolo dedicato adoxygen, che si possono settare impostando in modo opportuno il valoredei TAG nel �le di con�gurazione. É inoltre possibile speci�care a doxygenil linguaggio usato per scrivere il codice al �ne di ottimizzare il processodi generazione della documentazione.

Un altro punto molto importante a favore di doxygen è la possibilità di in-cludere nella documentazione, grazie all'uso sinergico di doxygen con gra-phviz, i vari diagrammi delle classi e gra� delle chiamate. Tali diagrammi,oltre ad arricchire la documentazione, potranno anche essere usati succes-sivamente per operazioni di manutenzione del software. Per tali motivi, ameno di esigenze speci�che, doxygen è lo strumento più consigliato.

26

• ROBODoc: La particolarità di ROBODoc è la possibilità di generaredocumentazione di codice scritto praticamente in qualsiasi linguaggio diprogrammazione. Il suo uso viene quindi consigliato per documentare �lesorgenti scritti con linguaggi di �nicchia� che sono quindi poco utilizzati enon hanno strumenti a supporto per la generazione della documentazione.ROBODoc consente inoltre un buon grado di libertà per quanto riguardal'output generato. É infatti possibile scegliere, oltre ai vari formati comeHTML, RTF e Latex, tre possibili modalità con cui produrre la docu-mentazione, ossia: multidoc, singledoc e single�le. Quest'ultima modalitàviene scelta perlopiù per e�ettuare operazioni di debugging.

• NaturalDoc: Il più grande limite di NaturalDoc è l'output generato.Esso infatti consente di generare solamente documentazione in formatoHTML. Per questo motivo il suo uso è sconsigliato se abbiamo bisogno digenerare documentazione consultabile o�-line. Una particolarità di Na-turalDoc è la possibilità di includere la documentazione in �le di testoa parte. Grazie a tale proprietà NaturalDoc può essere usato per docu-mentare quei programmi per cui non si ha accesso al codice sorgente o perdocumentare qualsiasi cosa estranea al codice stesso, come ad esempio l'ar-chitettura generale del programma. Ricordiamo che nella documentazioneè anche possibile includere immagini.

• HeaderDoc: HeaderDoc, sviluppato dalla Apple Inc., è disponibile soloper Mac e Linux, quindi è da escludere a priori tra le possibili scelte distrumenti di documentazione se si sta lavorando in Windows. La parti-colarità di HeaderDoc è la possibilità di collegare due o più set di docu-mentazione grazie allo strumento ResolveLinks che permette di collegaretra loro più �le di documentazioni separate. É consigliabile quindi quandodue o più team lavorano ad un unico progetto, generalmente sviluppatoin Swift, in modo tale che ogni team possa scrivere la documentazione delproprio lavoro per poi unire tutti i �le risultanti in uno solo di più grandidimensioni.

• phpDocumentor: phpDocumentor può essere utilizzato solo per progettiscritti in PHP, in quanto è l'unico linguaggio supportato da tale strumen-to. Resta allora da capire se per tale linguaggio è uno strumento valido dapoter utilizzare. La risposta è si. Infatti phpDocumentor fornisce mecca-nismi che permettono il riferimento incrociato, durante la documentazionedel progetto, alla documentazione u�ciale di PHP. Inoltre con tale stru-mento è possibile realizzare diversi tipi di documentazione, ognuno adattoa diverse �gure di utilizzatore del prodotto, ad esempio tutorial per gliutenti �nali del progetto.

27

4.6 Tabelle riepilogative

Nella tabella successiva diamo uno sguardo ai tools visti in questa tesi speci�-candone: autore, data del primo rilascio, ultima versione stabile prodotta e tipodi licenza sotto il quale sono rilasciati:

Ora mostriamo i sistemi operativi con cui tali strumenti possono operare:

Di seguito i linguaggi di programmazione supportati:

1General Public License2Apple Public Source License, software open-source rilasciato dalla Apple Inc.3Lesser General Public License, software con licenza free pubblicato dalla Free Software

Foundation(FSF)

28

In ultimo, ma non per importanza, la tabella che mostra con quali formatiè possibile creare la documentazione prodotta con gli strumenti qui visti:

29