Una introduzione piuttosto completa a JavaDoc. Vari Tag e descrizioni. Cenni alle caratteristiche più avanzate.

1. javaDoc
ovvero... Documentazione semplice
Prof. Marcello Missiroli
marcello.missiroli@gmail.com

2. Scopo
Scrivere codice è complicato
Mantenere codice altrui..di più!

3. Scopo
Scrivere codice è complicato
Mantenere codice altrui..di più!
Supportiamo gli sviluppatori
con la documentazione
Manutenzione
Riutilizzo

4. Cosa documentare?
Obbligatorio (con Javadoc):
Classi
Package
Costruttori, metodi e attibuti
Vivamente consigliato ( con /* */ e // )
Snippets poco chiari
Algoritmi
Cicli

5. Perché proprio Javadoc?
Generare documentazione di una API a mano è tedioso
e genera errori
Molti piccoli dettagli
Devo sincronizzare sorgente e documentazione
Devo duplicare gli sforzi (tipi, nomi. . . )
Mooolto meglio combinare codice e documentazione
Genero la documentazione dal codice
La documentazione interna al codice tende ad essere
più corretta

6. Infatti Javadoc....
Genera documentazione en HTML
Deduce correttamente informazioni quali nome,
tipi, classi... . .
Ulteriori infomazioni
Riferimenti incrociati
Molti IDE supportano Javadoc (es. Eclipse,
Netbeans)

7. Sintassi semplice
Basta premettere un testo con un particolare
formato al codice da commentare.
/**
*
* Descrizione principale (testo / HTML)
*
*
* Tags (testo / HTML)
*
*
*/

8. Esempio complesso
/**
* Returns the index of the first occurrence of the specified element in
* this vector, searching forwards from <code>index</code>, or returns ­1 if
* the element is not found.
*
* @param o element to search for
* @param index index to start searching from
* @return the index of the first occurrence of the element in
* this vector at position <code>index</code> or later in the vector;
* <code>­1</code> if the element is not found
* @throws IndexOutOfBoundsException if the specified index is negative
* @see Object#equals(Object)
*/
public int indexOf(Object o, int index) ...

9. Risultato

10. Regole base
La prima frase di ogni commento deve essere un
riassunto con una descrizione concisa e
completa, terminata da un punto e seguita da
uno spazio, tabulatore o n.
Marcare con <code> I nomi e le parole chiave
Preferibile l'uso della 3° persona
Iniziare con un verbo la descrizione dei metodi
Omettere il soggetto quando è ovvio

11. I tag Javadoc
Case sensitive!
Sono di due tipi: “block tag” e “inline tag”
Block tags
Si trovano nella descrizione principale, all'inizio della
riga. Es:
@tag
Inline tags
Si trovano nella descrizione principale O nella
descrizione dei block tag. Es:
{@tag}

12. Tag autoesplicativi
@author
@version
@since /* *
* A c l as s r e p r e s e n t i n g a
wi n d o w o n t h e s c r e e n .
@deprecated * @au t h o r S ami S h ai o
* @ve r s i o n %I %, %G%
@serial * @s e e
j ava. awt . Bas e W n d o w
i
* @s e e
%I e %G sono macro
j ava. awt . Bu t t o n
*/
settate c l as s W n d o w e x t e n d s
i
Bas e W n d o w { . . . }
i
automagicamente
dai sistemi di versioning (CVS, SVN, ...)

13. @param
Descrive i parametri dei metodi
name DEVE essere /*
uguale al nome * Th i s me t h o d wi l l s ay
hel l o
del parametro * i f yo u as k i t n i c e l y.
* @ am name Yo u r n ame .
par
* @ et ur n A f r i e n d l y
r
gr e e t i ng.
*/
p u b l i c St ri ng
He l l o ( n ame : S t r i n g ) : {
r e t u r n “ h e l l o ” + n ame ;
}

14. @return
Descrive i valori di ritorno
Documentare valori /*
di ritorno insoliti * Th i s me t h o d wi l l s ay
hel l o
come 0, null e * i f yo u as k i t n i c e l y.
* @ am name Yo u r n ame .
par
simile * @ et ur n A f r i e n d l y
r
gr e e t i ng.
*/
p u b l i c St ri ng
He l l o ( n ame : S t r i n g ) : {
r e t u r n “ h e l l o ” + n ame ;
}

15. @throws, @exception
Uno per ogni possibile eccezione
...
Spesso aggiunta * @exc ept i on
automaticamente Nu mb e r Fo r mat Ex c e p t i o n i f
t he s t ri ng d oe s not
Possibile anche per c o n t ai n a
* p ar s ab l e
le unchecked < c od e > l ong< /c od e > .
*/
exceptions p u b l i c s t at i c l o n g
p ar s e L o n g ( S t r i n g s )
t h r o ws
Nu mb e r Fo r mat Ex c e p t i o n
{. . . . }

16. @see
Aggiuge link ipertestuali aggiuntivi
/* *
* ...
* @s ee < a
Varianti h r e f = " h t t p : / / www. w3. o r g / WA
I / " > W b Ac c e s s i b i l i t y
e
I n i t i at i ve < / a>
@see String * @s ee
S t r i n g #e q u al s ( Ob j e c t )
@see <a href="URL"> e q u al s
*/
label</a> p u b l i c vo i d me t h o d ( )
{. . . }
@see
package.class#member label

17. @link package.class#member
Simile al precedente, ma in versione inline
Non genera /* *
cross-reference * Re t u r n s t h e c o mp o n e n t at
t he s pe ci f i e d i nd e x.
*
* Th i s me t h o d i s i d e n t i c al
i n f u n c t i o n al i t y t o
* t h e { @l i nk #g e t ( i n t ) }
* me t h o d ( wh i c h i s p ar t o f
t h e { @l i nk L i s t }
i n t e r f ac e ) .

18. @inheritDoc
Per le classi ereditate, si può ereditare anche la
relativa documentazione dalla classe padre, in
modo esplicito (automatico) o implicito.
Avviene in modo implicito....
Quando non si scrive una descrizione generale o un
tag @return, @param o @throws
Quando non sidescrive un tag @throws ma solo per
le checked exception

19. @inheritDoc (II)
Avviene in modo esplicito...
Usando il tag inline
/* *
{@inheritDoc} * ( s o t t o c l as s e ) .
*
* @t h r o ws
Nu l l Po i n t e r Ex c e p t i o n
{ @i nher i t Doc }
*/
p u b l i c vo i d g e t Ch ar s ( i n t
s r c Be g i n , i n t s r c En d , c h ar
d s t [ ] , i n t d s t Be g i n ) {

20. JavaDoc avanzato (da Java
5)
Doclet
Permettono di generare vari di tipi di
documento (es: PDF)
Taglet
Permettono di usare tag personalizzati
UMLGraph
Permettono di generare grafici UML
Annotations
Documentazione più raffinata.

21. Integrato in Netbeans!
Scrivere la documentazione
Si noti che il commento all'interno di un Jdoc è
formattato automaticamente!
Selezionare “Run > Generate Javadoc”
Il browser si apre sulla documentazione
La documentazione si trova nel progetto, cartella
“doc”
Simili funzionalità in altri IDE
Simili funzionalità in altri linguaggi (es. PHP)

22. Riassumendo...
Supportate gli sviluppatori
con la documentazione
Usate JavaDoc
Commentate
Aggiornate
Vivete felici

23. Bibliografia
Andrea Gallidabino, Florian Gysin – Intro to Tdoc
MADS Group - Departamento de Computacion –
Documentando con Javadoc, Introduccion
Documentazione ufficiale Java – http://docs.oracle.com
Questo documento è dotato di licenza CreativeCommon BY-
SA 3.0
http://creativecommons.org/licenses/by-sa/3.0/deed.it