Transcript Elaborato Del Gaudio Carmine n46000753

Scuola Politecnica e delle Scienze di Base
Corso di Laurea Magistrale in Ingegneria
Informatica
Tesi di Laurea Magistrale in Ingegneria del Software
Un confronto tra Generatori di Documentazione
Anno Accademico 2015/16
relatore
Prof. Porfirio Tramontana
candidato
Carmine Del Gaudio
matr. N46000753
INDICE
Un 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 Documentazione
La 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 codice
Scrivere 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 soluzioni
Ci 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 GENERAZIONE
AUTOMATICA DELLA
DOCUMENTAZIONE
SOMMARIO: 2.1 Javadoc; 2.2 Doxygen; 2.3 Natural Docs
5
2.1 Javadoc
Javadoc è 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
@author
@deprecated
@exception
@throws
@link
@param
@return
@see
@since
@version
DESCRIZIONE
Seguito dal nome dell’autore o degli autori
Indica un elemento obsoleto utilizzato in una precedente
versione
Sono sinonimi ed indicano un’entità che può sollevare
eccezioni
Crea un collegamento ipertestuale
Indica i parametri di un metodo
Indica il valore di ritorno di quel metodo
Indica una associazione ad un altro metodo o classe
Indica da quale versione quell’elemento esiste
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
* @since
1.1
*/
public class myClass {
// class body
}
(la versione corrente)
(da quale versione è presente)
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 Doxygen
Doxygen è 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 Docs
Natural 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
*/
FUNZIONE
int 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 testo
per 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 Input
Come 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 Output
Per 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 commenti
di 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 documentazione
Di 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 Conclusioni
In 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