Scuola Politecnica e delle Scienze di BaseCorso di Laurea Magistrale in Ingegneria Informatica

Tesi di Laurea Magistrale in Ingegneria del Software

Un confronto tra Generatori di Documentazione

Anno Accademico 2015/16

relatoreProf. Porfirio Tramontana

candidatoCarmine Del Gaudiomatr. N46000753

INDICEUn confronto tra Generatori di Documentazione

CAPITOLO I INTRODUZIONE...........................................................................................................................1 1. La Documentazione.....................................................................................................................2 1.1 Importanza della documentazione del codice.......................................................................3 1.2 Problemi e soluzioni.............................................................................................................4

CAPITOLO II SOFTWARE DI GENERAZIONE AUTOMATICA DELLA DOCUMENTAZIONE...................5 2.1 Javadoc.................................................................................................................................6 2.1.1 Formato dei commenti..................................................................................................7 2.1.2 Configurazione del tool................................................................................................9 2.1.3 Personalizzazione.......................................................................................................11 2.2 Doxygen.............................................................................................................................12 2.2.1 Formato dei commenti................................................................................................13 2.2.2 Configurazione del tool..............................................................................................15 2.2.3 GUI.............................................................................................................................17 2.3 Natural Docs.......................................................................................................................20 2.3.1 Formato dei commenti................................................................................................21 2.3.2 Configurazione del tool..............................................................................................24

CAPITOLO III CONFRONTO...............................................................................................................................25 3.1 Input....................................................................................................................................26 3.2 Output.................................................................................................................................26 3.3 Formato dei commenti........................................................................................................27 3.4 Usabilità..............................................................................................................................29 3.5 Estrazione della documentazione.......................................................................................29 3.5.1 Classe che non fa nulla...............................................................................................29 3.5.1 Progetto non documentato..........................................................................................31 3.6 Conclusioni.........................................................................................................................31

SITOGRAFIA

CAPITOLO I

INTRODUZIONE

SOMMARIO:1. La Documentazione; 1.1 Importanza della documentazione

del codice;1.2 Problemi e soluzioni

1

1. La DocumentazioneLa documentazione è un testo che accompagna il software e che ne descrive il

comportamento e l’utilizzo. Il processo di scrittura della documentazione

accompagna le varie fasi dello sviluppo di un software così da generare vari

tipi di documentazione:

• Documentazione dei requisiti:

serve a specificare le caratteristiche che il software deve avere.

• Documentazione dell’architettura:

si occupa di spiegare la struttura del software e delle parti che lo

compongono.

• Documentazione del codice:

descrive il funzionamento del codice sorgente.

• Documentazione utente:

è un manuale dettagliato che si illustra all’utente le funzioni del

software e come utilizzarlo.

• Documentazione Marketing:

utile alla promozione e alla diffusione del software.

Da qui in poi quando si utilizzerà il termine “documentazione” si intenderà la

documentazione del codice.

2

1.1 Importanza della documentazione del codiceScrivere un software di buona qualità non significa semplicemente scrivere del

buon codice ma bisogna allegare gli strumenti per una facile comprensione e

manutenzione.

Spesso, purtroppo, si dà poca importanza alla scrittura di una buona

documentazione, talvolta vista come un’attività lunga e noiosa.

Può capitare, ad esempio, che per velocizzare il rilascio di una versione

funzionante del software il programmatore privilegi lo sviluppo del codice e

sul suo corretto funzionamento tralasciando o rimandando la scrittura della

documentazione. Successivamente l’autore potrebbe dover riprendere quel

codice,o per il fix di bug o per rilasciare una nuova versione che aggiunga

feature aggiuntive, trovandosi così il problema che molto probabilmente il

programmatore non ricorderà più come e perché ha eseguito determinate scelte

di programmazione, spendendo così molto tempo ed energie a rileggere il

vecchio codice e rendendo inutile il tempo inizialmente risparmiato.

Un altro esempio da prendere in considerazione è che lavorando in una

azienda si faccia parte di un team. In questo caso c’è da tener conto che ogni

sviluppatore ha il proprio stile e approccio alla programmazione quindi anche

avendo delle direttive precise i programmatori dovranno spiegare ai propri

colleghi la propria porzione di codice.

Un ultimo esempio rilevante è lo sviluppo di software Open Source. In

quest’ultimo caso i programmatori solitamente si coordinano tramite canali

disorganizzati come mailing list e forum, non c’è la struttura organizzativa di

una azienda, ma ogni autore decide di dare il proprio contributo.

In assenza di una documentazione ben strutturata ogni autore che vuole

contribuire al progetto è costretto a rileggere la maggior parte del codice fino a

3

comprenderne il funzionamento, sfavorendo così la partecipazione a progetti

ampi. Non a caso i prodotti Open Source meglio documentati sono anche

quelli con più contributi.

1.2 Problemi e soluzioniCi sono quattro problemi principali da tenere in considerazione:

• La scrittura della documentazione essendo tra le ultime operazioni

svolte viene fatta in modo superficiale.

• Essendo passato del tempo dalla scrittura delle varie funzioni si

potrebbe avere un ricordo parziale delle motivazioni che hanno portato

a determinate scelte di sviluppo.

• Nel caso si modifichi il codice la documentazione deve essere

aggiornata manualmente.

• In caso di progetti molto ampi è impossibile avere manualmente una

documentazione completa e scritta secondo uno schema coerente.

Fortunatamente grazie a software di generazione automatica della

documentazione è possibile risolvere parzialmente o completamente questi

problemi.

Infatti la documentazione in questi casi va scritta durante la stesura del codice

sotto forma commenti adeguatamente formattati e poi interpretati dal software

che genererà automaticamente una documentazione completa, semplice da

consultare e in un formato che ne permetta una agevole navigazione. Inoltre i

commenti saranno scritti nella stessa pagina del codice precedendo le funzioni

che lo compongono, quindi quando si va ad aggiornare il codice

contestualmente è semplice modificare anche i commenti che andranno a

formare la documentazione.

4

CAPITOLO II

SOFTWARE DI GENERAZIONEAUTOMATICA DELLADOCUMENTAZIONE

SOMMARIO: 2.1 Javadoc; 2.2 Doxygen; 2.3 Natural Docs

5

2.1 JavadocJavadoc è stato sviluppato dalla Sun Microsystem nel 1990. Inizialmente

chiamato Javadoc è nato come strumento interno, utilizzato dai ricercatori

della Sun per la scrittura della documentazione del linguaggio Java e delle sue

librerie. Data la grande mole di classi, attributi e metodi era necessario avere

un software che generasse automaticamente la documentazione in un formato

che ne rendesse la consultazione semplice, organizzata ed efficace, per questo

si scelse di scrivere in linguaggio HTML dei commenti con all’interno

informazioni sul codice sviluppato.

Javadoc è oggigiorno lo strumento di documentazione del codice più utilizzato

per il linguaggio Java e viene distribuito insieme al Java Development Kit.

Col passare del tempo si è arricchito di funzioni come: la possibilità di

generare documentazione in altri formati(PDF, Word, RTF, Microsoft Help,

LaTeX, ecc.) ,l’inserimento di link, l’aggiunta di opzioni di formattazione

avanzata, la possibilità di personalizzare il software con Taglet e Doclet.

Il processo di generazione della documentazione avviene in tre fasi:

• Scrittura dei commenti

• Configurazione del tool

• Generazione nel formato richiesto

le prime due sono da fare manualmente mentre la terza è completamente

automatica

6

2.1.1 Formato dei commenti

I commenti Javadoc sono dei blocchi racchiusi fra le sequenze “/**” e “*/”

dove all’interno del blocco ogni riga comincia col carattere “*”.

/** * Questo è un commento Javadoc */

I commenti devono essere posti immediatamente prima di una qualunque

entità che si vuole documentare(classe, interfaccia,metodo, ecc.).

Si possono suddividere in due parti:

• Descrizione dell’entità: nella parte superiore viene aggiunta una

brevissima descrizione e nella riga successiva, se necessaria, una

descrizione più dettagliata ma concisa.

• Tag: vengono posti subito dopo la descrizione e sono preceduti dal

simbolo “@”.

I i Tag più utilizzati sono:

TAG DESCRIZIONE@author Seguito dal nome dell’autore o degli autori@deprecated Indica un elemento obsoleto utilizzato in una precedente

versione@exception@throws

Sono sinonimi ed indicano un’entità che può sollevare eccezioni

@link Crea un collegamento ipertestuale@param Indica i parametri di un metodo@return Indica il valore di ritorno di quel metodo@see Indica una associazione ad un altro metodo o classe@since Indica da quale versione quell’elemento esiste@version Indica il numero di versione di un elemento

7

I tag sopra citati sono molto utili per avere una documentazione completa, di

seguito si riportano alcuni esempi di documentazione:

Documentazione di una classe

/** * @author Nome Cognome * @version 1.7 (la versione corrente) * @since 1.1 (da quale versione è presente) */public class myClass { // class body}

Documentazione di un metodo

/** * Descrizione breve. * <p> * Informazioni aggiuntive sul metodo. * <p> * altre spiegazioni sul metodo. * * @param var1 descrizione del primo parametro. * @param var2 descrizione del secondo parametro. * @return descrizione del valore ritornato. */public int methodName (int var1, int var2) { // method body with a return statement}

Documentazione di una variabile

/** * descrizione della variabile 1. */public int var1;

/** * descrizione della variabile 2. */public int var2;

8

2.1.2 Configurazione del tool

In questa trattazione si analizzerà come utilizzare Javadoc prima da linea di

comando su Windows e poi all’interno di Eclipse.

Su Windows eseguendo il comando “Javadoc -help” si ottiene il seguente

output dove sono illustrate le varie opzioni che il comando Javadoc offre.

Le più utilizzate sono le seguenti:

• -overview : indica il file contenente l’introduzione del progetto.

• -public, -protected, -package, -private: indicano la

visibilità della documentazione, mettendo -package verrà generata la

documentazione per tutto il codice, con -public, invece, solo quella

relativa ad elementi di pubblica visibilità.

• -d:indica la cartella di destinazione della documentazione.

• -sourcepath, -classpath, -cp: indicano la posizione del codice

da documentare.

9

Con Eclipse invece ci viene fornita una GUI che ne facilita utilizzo:

Qui è possibile selezionare le cartelle o i singoli file che si vogliono includere

nella documentaizone, la visibilità della documentazione e l’utilizzo di Doclet

per la personalizzarne l’output.

Cliccando su “Next>” vi sono ulteriori opzioni di personalizzazione mentre su

“Finish” si genera la documentazione con le impostazioni predefinite.

10

2.1.3 Personalizzazione

La personalizzazione della documentazione in Javadoc avviene attraverso

Taglet e Doclet.

Un Doclet è una porzione di codice che definisce l’aspetto e il formato della

documentazione.

Un Taglet, invece, permette la creazione di un tag personalizzato che

all’interno della documentazione abbia una propria formattazione, inoltre è

anche possibile sovrascrivere i tag standard.

Il formato della Doclet standard è HTML, ma è possibile scrivere Doclet

anche per SGML, XML, RTF, ecc.

L’elevata personalizzabilità delle Doclet ha permesso la creazione di strumenti

molto diversificati, come ad esempio la creazione di schemi UML molto

utilizzati nell’ingegneria del software.

Se non viene specificato esplicitamente Javadoc utilizzerà il Doclet standard

che è composta da tre package:

• com.sun.tools.doclets che si occupa della gestione dei Taglet e

dell’output HTML

• com.sun.tools.doclets.standard contenente le classi utili alla

creazione delle pagine

• com.sun.tools.doclets.standard.tags contenente tutti i

Taglet disponibili

11

2.2 DoxygenDoxygen è un tool Open Source scritto per la maggior parte da Dimitri Heesch

del 1997. Il programma è stato sviluppato inizialmente per Mac OS X e Linux

ma data la sua elevata portabilità oggi può essere eseguito su Windows e sulla

maggior parte dei sistemi Unix.

È il tool di generazione automatica della documentazione di gran lunga più

utilizzato nei grandi progetti Open Source in C++, ma può essere utilizzato su

un gran numero di altri linguaggi come: C, Objective-C, C#, PHP, Java,

Python, IDL, Fortran, VHDL, ecc.

Come impostazione predefinita genera la propria documentazione in HTML e

LaTeX, supporta inoltre anche LaTeX, RTF, PostScript, PDF con collegamenti

ipertestuali, HTML compresso e pagine di manuale Unix.

Si distingue per la sua capacità di estrarre la struttura del codice dai file

sorgente non documentati,per poi visualizzarla mediante grafici generati in

automatico.

I documenti inoltre possono essere generati in diverse lingue tra cui è

compreso anche l’italiano

12

2.2.1 Formato dei commenti

Doxygen come Javadoc prevede che la documentazione sia scritta in

commenti adeguatamente formattati e supporta sia il formato Javadoc visto

precedentemente sia il formato Qt-Doc.

//blocco commento Javadoc //blocco commento Qt-Doc

/** /*!

*Descrizione metodo Descrizione metodo

* @param x parametro \param x parametro

* @return output \return output

*/ */

/// riga commento Javadoc. //! riga commento Qt-Doc.

Il tool prevede che i commenti siano subito sopra l’elemento da commentare

fatta eccezione per parametri e funzioni che possono anche essere commentati

nel modo seguente:

int j; /**< commento Javadoc */

int q; /*!< commento Qt-doc */

come si vede il commento comincia con un simbolo “<”.

Anche in questo caso la documentazione si divide in due parti:

• una prima parte composta dalla descrizione dell’elemento da

documentare ed è chiamata brief.

• una successiva composta che può essere realizzata o con i classici Tag

Javadoc(@tag) o con dei Markup Qt-doc(\markup)

la parte descrittiva in Doxygen è facoltativa e può anche essere nascosta

settando BRIEF_MEMBER_DESC=NO nel file di configurazione.

La prima riga sarà considerata in automatico come brief, per disattivare questo

comportamento bisogna modificare il file di configurazione e impostare

Javadoc_AUTOBRIEF=NO se si utilizza il formato commento Javadoc,

QT_AUTOBRIEF=NO se si utilizza quello Qt-Doc.

13

Per per quanto riguarda invece la seconda parte riportiamo una tabella con i

Markup più interessanti di Doxygen per Java

Markup Descrizione

\author Indica l’autore del codice

\b, \e Rispettivamente: blood e italic

\f$ Comincia e termina la scrittura di una formula matematica

\mainpage Indica che la seguente sezione comparirà sulla pagina principale

\n Inizia una nuova riga

\par Inzia un nuovo paragrafo

\param Utile per descrivere un parametro

\return Utile per descrivere il valore di output

\sa Sta per “see also” e indica un elemento collegato in qualche modo all’elemento documentato, corrisponde al @see di Javadoc

\todo Lascia una nota riguardo qualcosa da realizzare

\version Indica la versione di un elemento del codice

\warning Utile per lasciare un avviso

Per creare una lista invece è sufficiente mettere il simbolo “-” o “+” all’inizio

di ogni elemento della lista, per una lista numerata si usa invece “-#”.

Doxygen inoltre supportando lo standard Javadoc riconosce anche i comandi

HTML.

14

2.2.2 Configurazione del tool

Doxygen non ha una GUI ma si utilizza attraverso comandi da terminale.

Utilizzando il comando “doxygen -h” otteniamo il seguente output:

quindi per ottenere il file di configurazione dobbiamo eseguire il comando

“doxygen -g” che genererà in automatico un file di testo chiamato Doxyfile

lungo più di 2000 righe contenente al proprio interno le preferenze per la

propria documentazione e le relative spiegazioni, alcune di queste sono state

già trattate nel paragrafo precedente per quanto riguarda la riga di descrizione

breve.

15

Riportiamo di seguito le impostazioni più rilevanti:

Comando Descrizione

PROJECT_NAME Imposta il nome del progetto, "My Project" è impostato come predefinito

PROJECT_NUMBER Imposta la versione del progetto

PROJECT_LOGO Imposta un logo che viene incluso nella documentazione

OUTPUT_DIRECTORY Imposta la cartella dove verrà salvata la documentazione

INPUT Imposta la posizione del progetto da documentare

OUTPUT_LANGUAGE Imposta la lingua della documentazione

EXTRACT_ALL Se attivo genera la documentazione per tutti gli elementi anche per quelli non ancora commentati

SOURCE_BROWSER Se attivo il programma genera un elenco dei file sorgente con riferimenti incrociati

OPTIMIZE_OUTPUT_JAVA Ottimizza la documentazione per i progetti scritti in java

CLASS_GRAPH Se attivo verrò generato un grafico contenente ogni classe documentata e le relazioni tra le classi

GENERATE_LaTeX Genera un file LaTeX e un makefile in modo che si possa compilare in PostScript, PDF, ecc.

GENERATE_HTML Genera la documentazione HTML, includendo anche i diagrammi di glasse

WARN_FORMAT Configura il comportamento dei warning

GENERATE_TREEVIEW Genera un indice sidebare per l’HTML

16

2.2.3 GUI

Come detto il precedenza Doxygen non fa affidamento su una interfaccia

grafica predefinita ma viene configurato ed eseguito attraverso il terminale.

Per utilizzare invece una più confortevole interfaccia grafica vi sono due

possibili modi:

• Doxywizard

• Eclox

il primo è un tool da installare tramite eseguibile su Windows, il secondo

invece è una estensione di Eclipse scaricabile attraverso il marketplace interno

all’ambiente di sviluppo.

Installato Eclox comparirà in Eclipse una icona con il simbolo “@”,

cliccandoci sopra verrà richiesto il file di configurazione di Doxygen, è

possibile a questo punto fornirne uno preconfigurato o generarne uno

predefinito all’interno del progetto.

Aprendo con Eclipse il file generato possiamo notare che l’interfaccia è molto

simile quella che abbiamo eseguendo il programma Doxywizard.

Successivamente si utilizzeranno esempi e immagini presi da Eclox ma ciò che

si dirà vale per entrambi i tool.

L’interfaccia si divide in due schede: Basic per una configurazione più rapida

e Advanced che invece è più dettagliata, è possibile utilizzare entrambe le

modalità per personalizzare la propria documentazione, nella scheda Basic si

fa una prima configurazione generale e successivamente la si affina nella

Advanced.

17

La scheda Basic si divide in quattro parti:

• Project: dove indica il nome del progetto, la versione, il percorso dove è

contenuto e la cartella dove salvare la documentazione generata.

• Mode: si occupa delle modalità di analisi del codice sorgente.

• Output Formats: configura il formato della documentazione.

• Diagrams to Generate: mostra le opzioni per la generazione dei

diagrammi, è possibile utilizzare un generatore interno oppure

GraphViz, un tool Open Source con maggiori opzioni per la

configurazione dei grafici.

18

La scheda Advanced invece è molto simile al file testuale di

configurazione ma graficamente più elegante.

È divisa in due parti: a sinistra c’è la lista delle possibili impostazioni,

mentre a destra c’è una nota che spiega e configura quel parametro.

19

2.3 Natural DocsNatural Docs è un tool creato e per la maggior parte sviluppato da Greg

Valure. È scritto in Perl ma teoricamente può generare documentazione per

qualsiasi linguaggio di programmazione che supporti un marcatore di

commenti, è anche molto portabile in quanto è possibile eseguirlo ovunque

può essere eseguito un software Perl.

Per i linguaggi ActionScript 2.0, C# e Perl è in grado di generare la

documentazione automaticamente, anche in assenza di commenti nel codice,

mentre, per gli altri linguaggi di programmazione essa viene estratta da

commenti adeguatamente formattati.

Interessante in Natural Docs è il sistema di donazioni, infatti nel come appena

detto il software supporta in modo completo solo tre linguaggi di

programmazione, ma è possibile richiedere, con delle donazioni, che nelle

prossime versioni si preferisca migliorare il supporto ad un linguaggio di

programmazione rispetto ad un altro.

Inoltre se si programma con un linguaggio non ancora supportato è possibile

comunque generare la documentazione modificando il file di configurazione in

modo appropriato.

Per quanto riguarda invece l’output Natural Docs offre solo il formato HTML

molto personalizzabile grazie ad una struttura CSS che definisce lo stile e

l’aspetto.

È semplice muoversi all’interno della documentazione generata anche grazie

ad uno strumento di ricerca generato automaticamente dal tool in formato

DHTML che funziona sia su un server online, sia sulla propria copia offline

della documentazione.

20

2.3.1 Formato dei commenti

Natural Docs è in grado di leggere sia i commenti scritti all’interno del codice

sia in file di testo(.txt) presente all’interno del progetto, trattandolo

esattamente come un file sorgente e allegandolo alla documentazione, questa

soluzione viene spesso adottata per scrivere una introduzione al progetto.

Per quanto riguarda i commenti scritti all’interno del codice l’unica

limitazione che impone è che non siano scritti sulla stessa riga del codice.

Natural Docs non prevede un proprio formato standard per i commenti, ma è

in grado di creare della documentazione da commenti scritti in linguaggio

naturale e Javadoc, quest'ultimo solo nei linguaggi supportati completamente.

Di seguito viene riportato un esempio preso dalla documentazione di Natural

Docs:

COMMENTO NATURAL DOCS/* * Function: Multiply * * Multiplies two integers. * * Parameters: * x - The first integer. * y - The second integer. * * Returns: * The two integers multiplied together. * * See Also: * <Divide> */COMMENTO Javadoc/** * Multiplies two integers. * * @param x The first integer. * @param y The second integer. * @return The two integers multiplied together. * @see Divide */ FUNZIONEint Multiply (int x, int y) { return x * y; };

21

Una prima cosa che si può notare è che mentre per scrivere un commento

Javadoc è necessario cominciare il commento con la stringa “/**” in Natural

Docs non è prevista un formato particolare per i commenti ma utilizza i

semplici commenti Java.

Inoltre non sono presenti tag ma il tool dispone di molte Keyword per definire

gli elementi che si sta documentando, nell’esempio precedente possiamo

vedere: “function”, “parameters”, “returns” e “see also”, sono molto

intuitive e non sono case sensitive, inoltre sono presenti molti sinonimi per

rendere la scrittura della documentazione quanto più naturale possibile.

Nell’esempio si vede anche il link all’elemento “Divide”, infatti in Natural

Doc è possibile creare link ponendoli all’interno di due parentesi angolate, si

possono creare anche link esterni come <https://it.wikipedia.org> .

Di seguito viene riportata l’output del precedente esempio.

22

Si noti che Natural Docs include il codice all’interno della propria

documentazione.

Il tool mette a disposizione anche la possibilità formattare il testo in uscita:

• Per avere del testo in grassetto è sufficiente racchiudere il testo tra due

“*”, ad esempio *bold text* .

• Per del testo sottolineato invece il testo deve essere inserito tra due “_”,

ad esempio _underlined text_ .

• Per creare una lista puntata invece è necessario cominciare ogni riga

con uno dei seguenti simboli: “-”, “o”, “*”, “+”.

È possibile possibile anche aggiungere delle immagini alla documentazione

usando la stringa (see filename) con al posto di “filename” il nome

dell’immagine.

23

2.3.2 Configurazione del tool

Il tool non prevede una interfaccia grafica ma viene utilizzato attraverso il

terminale. Per estrarre la documentazione da un progetto è necessario digitare

il seguente comando:

NaturalDocs -i [input (source) directory] -o [output format] [output directory] -p [project directory] [options]

Mentre eseguendo il comando “NaturalDocs -h” è possibile avere una lista

dei comandi di configurazione del tool, di seguito ne riportiamo alcuni:

Comandi Descrizione

-i Cartella o cartelle contenenti il progetto da documentare

-o Specifica il formato della documentazione e la cartella che la conterrà

-p Cartella del progetto dove saranno posti tre file di testoper la personalizzazione della documentazione

-img Cartella contenente le immagini da importare

-s Definisce lo stile della documentazione, i predefiniti sono Default, Small e Roman

-do Richiede che gli elementi non commentati non siano inclusi nella documentazione

-xi Esclude una cartella dalla documentazione

Nella cartella del progetto vengono generati automaticamente tre file:

• Languages.txt contiene le impostazioni per il linguaggio di

programmazione e per la definizione di un nuovo linguaggio.

• Menu.txt contiene le impostazioni del menù, è possibile aggiungere un

titolo, un pedice e un timestamp.

• Topics.txt dove si configurano le Keyword, l’indice e tutto ciò che

riguarda la sintassi.

24

CAPITOLO III

CONFRONTO

SOMMARIO: 3.1 Input; 3.1 Output; 3.3 Formato dei commenti; 3.3 Usabilità;

3.4 Estrazione della documentazione; 3.5 Conclusioni

25

3.1 InputCome detto in precedenza il tool più utilizzato per la generazione di

documentazione di software scritti in Java è Javadoc, questo perché può

basarsi sul compilatore Javac che è garanzia per la documentazione generata.

D’altra parte però Javadoc può essere eseguito solo su software scritti in

linguaggio Java mentre di Doxygen che invece supporta C, Objective-C, C#,

PHP, Java, Python, IDL, Fortran, VHDL, ecc.

Natural Docs può essere eseguito su 19 linguaggi di programmazione

differenti, ma solo C#, Perl e ActionScript 2.0 sono supportati in modo

completo, è possibile inoltre configurare nuovi linguaggi di programmazione

manualmente, in pratica questo software può essere utilizzato su qualsiasi

linguaggio che disponga di un marcatore per i commenti.

3.2 OutputPer quanto riguarda il formato di uscita sia Javadoc che Doxygen sono

provvisti di strumenti per poter personalizzare il formato e l’aspetto della

documentazione prodotta, Natural Docs invece supporta solo il formato

HTML.

Il formato predefinito per la documentazione in Javadoc è HTML ma

attraverso le Doclet è possibile generare documentazione in LaTeX, Word,

RTF, ecc inoltre ci sono Doclet che generano grafici UML di dipendenza fra

classi e package.

Doxygen invece prevede già la possibilità di generare la documentazione in

LaTeX, RTF, PostScript, PDF, ecc. e può anche generare di predefinito grafici

UML, o con un tool interno o con GraphViz.

26

3.3 Formato dei commentidi seguito si riporta un elenco di differenze:

• Per cominciare ricordiamo che Doxygen è in grado di interpretare i

commenti in formato Javadoc applicato a qualsiasi linguaggio mentre

Natural Docs solo per i linguaggi Perl, C# e ActionScript 2.0.

• I commenti rilevati dal tool Javadoc devono tutti iniziare con la stringa

“/**” o “///”, lo stesso vale per Doxygen ma supporta anche il formato

Qt-Doc che comincia con la stringa “/*!” o “//!”, al contrario Natural

Docs utilizza i commenti standard .

• In Javadoc i commenti possono essere scritti solo prima dell’elemento

da documentare, in Doxygen possono anche essere scritti dopo

utilizzando la stringa “/**<” o “/*!<”, mentre in Natural Docs è

possibile scrivere ovunque la documentazione anche in un file di testo

separato ma non sulla stessa riga del codice.

• Javadoc e Doxygen interpretano entrambi il codice HTML all’interno

dei commenti, ma in più Doxygen supporta anche comandi strutturali,

Natural Docs invece ha solo comandi strutturali e non prevede l’uso di

HTML nei commenti.

• Doxygen non ha bisogno di tag particolari per generare dei link

ipertestuali ma li riconosce automaticamente, mentre Natural Docs

necessita che l’oggetto sia compreso tra due parentesi angolate e

Javadoc utilizza il tag “{@link }” .

• Doxygen e Natural Docs hanno uno strumento interno di ricerca,

Javadoc no.

• Doxygen e Natural Docs inseriscono di predefinito il codice sorgente

nella documentazione, Javadoc no.

27

Nella pagina seguente riportiamo un esempio di commenti scritti per i relativi

tool.

Javadoc/** * This is <b>the</b> Rectangle class. * <p> * Refer to <a href="./doc-files/shapes-overview.html"> * shape-overview</a> for more details. * <p> * There are four types of supported {@link Shape}: * <ul> * <li>{@link Rectangle} (this class)</li> * <li>{@link Circle}</li> * <li>{@link Square}</li> * <li>{@link Triangle}</li> * </ul>*/

DOXYGEN/** * This is \b the Rectangle class. * * Refer to \ref shape-overview for more details. * * * There are four types of supported Shape: * - Rectangle (this class) * - Circle * - Square * - Triangle*/

NATURAL DOCS/* * Class: Rectangle * * This is *the* Rectangle class. * * Refer: * <shape-overview> for more details. * * There are four types of supported <Shape>: * - <Rectangle> (this class) * - <Circle> * - <Square> * - <Triangle> */

28

3.4 UsabilitàCome visto in precedenza Javadoc è contenuto all’interno del JDK e viene

riconosciuto automaticamente all’interno Eclipse nel quale presenta una

interfaccia molto intuitiva e semplice da configurare. In Eclipse inoltre è

completamente integrato, è sufficiente passare il mouse su un elemento per

visualizzarne la relativa documentazione.

Natural Docs invece è utilizzabile solo attraverso un terminale.

Allo stesso modo Doxygen non prevede una interfaccia grafica nella sua

versione base, ma può essere affiancato o dal tool Doxywizard o

dall’estensione Eclipse Eclox.

3.5 Estrazione della documentazioneDi seguito si analizzerà la documentazione di alcuni progetti scritti in Java

3.5.1 Classe che non fa nulla

prendiamo come primo esempio il seguente progetto contenente una classe

vuota e non documentata.

public class myClass {//questa classe non fa nulla}

Procedendo all’estrazione della documentazione otteniamo che:

• Natural Docs non genera alcun file, in quanto Java è supportato solo

parzialmente.

• Doxygen genera una documentazione abbastanza misera con all’interno

un link al codice sorgente.

• Javadoc genera un costruttore e produce una documentazione

abbastanza completa nonostante la semplicità del progetto

29

Javadoc:

Doxygen:

30

3.5.1 Progetto non documentato

Questa volta si consideri invece il package Java java.awt.color da cui sono

stati tolti tutti i commenti Javadoc, eseguendo il tool Javadoc e quello

Doxygen sul progetto si otterrà due documentazioni abbastanza simili, non

complete ma con una struttura generale del programma di seguito riporteremo

alcune differenze riscontrate:

• Nella scheda “package” Javadoc raggruppa le classi che definiscono

delle eccezioni dalle altre.

• Anche in questo caso Javadoc estrae per ogni classe un costruttore

anche dove non è esplicitato, Doxygen riesce a farlo solo se scritto in

modo esplicito.

• Doxygen inserisce all’interno della documentazione il codice sorgente

• Doxygen inserisce dei diagrammi delle classi

3.6 ConclusioniIn conclusione quindi si può notare che lo sviluppo di Natural Docs non è

abbastanza avanzato nel linguaggio Java per poter competere con Doxygen e

Javadoc ma resta comunque un tool molto interessante sia per la possibilità di

poter documentare qualsiasi linguaggio di programmazione che disponga di un

marcatore per i commenti, sia per il formato dei commenti che possono essere

scritti in linguaggio molto naturale e di facile lettura.

Javadoc e Doxygen invece si sono dimostrati tool molto validi, anche in caso

di assenza di commenti all’interno del codice, e anche se da una parte Javadoc

riesce ad estrapolare maggiori informazioni dai programmi scritti in Java,

dall’altra Doxygen può contare su una forma più compatta e leggibile di

commenti

31

SITOGRAFIA

https://en.wikipedia.org/wiki/Software_documentation

https://it.wikipedia.org/wiki/Software_documentation

https://en.wikipedia.org/wiki/Javadoc

http://www.oracle.com/technetwork/articles/java/index-137868.html

https://en.wikipedia.org/wiki/Doxygen

http://www.stack.nl/~dimitri/doxygen/

https://en.wikipedia.org/wiki/Natural_Docs

http://www.naturaldocs.org/features.html

https://en.wikipedia.org/wiki/Comparison_of_documentation_generators

http://gushieblog.blogspot.it/2006/06/doxygen-versus-Javadoc.html

https://docs.oracle.com/javase/7/docs/api/

32