Una introduzione piuttosto completa a JavaDoc. Vari Tag e descrizioni. Cenni alle caratteristiche più avanzate.
2. ScopoScrivere codice complicatoMantenere codice altrui..di
pi! 3. ScopoScrivere codice complicatoMantenere codice altrui..di
pi!Supportiamo gli sviluppatori con la
documentazioneManutenzioneRiutilizzo 4. Cosa
documentare?Obbligatorio (con Javadoc):ClassiPackageCostruttori,
metodi e attibutiVivamente consigliato ( con /* */ e // )Snippets
poco chiariAlgoritmiCicli 5. Perch proprio Javadoc?Generare
documentazione di una API a mano tedioso e genera erroriMolti
piccoli dettagliDevo sincronizzare sorgente e documentazioneDevo
duplicare gli sforzi (tipi, nomi. . . )Mooolto meglio combinare
codice e documentazioneGenero la documentazione dal codiceLa
documentazione interna al codice tende ad essere pi corretta 6.
Infatti Javadoc....Genera documentazione en HTMLDeduce
correttamente informazioni quali nome, tipi, classi... . .Ulteriori
infomazioniRiferimenti incrociatiMolti IDE supportano Javadoc (es.
Eclipse, Netbeans) 7. Sintassi sempliceBasta premettere un testo
con un particolare formato al codice da
commentare./****Descrizioneprincipale(testo/HTML)***Tags(testo/HTML)***/
8. Esempio
complesso/***Returnstheindexofthefirstoccurrenceofthespecifiedelementin*thisvector,searchingforwardsfromindex,orreturns1if*theelementisnotfound.**@paramoelementtosearchfor*@paramindexindextostartsearchingfrom*@returntheindexofthefirstoccurrenceoftheelementin*thisvectoratpositionindexorlaterinthevector;*1iftheelementisnotfound*@throwsIndexOutOfBoundsExceptionifthespecifiedindexisnegative*@seeObject#equals(Object)*/publicintindexOf(Objecto,intindex)...
9. Risultato 10. Regole baseLa 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 I nomi e le parole chiavePreferibile luso della 3
personaIniziare con un verbo la descrizione dei metodiOmettere il
soggetto quando ovvio 11. I tag JavadocCase sensitive!Sono di due
tipi: block tag e inline tagBlock tagsSi trovano nella descrizione
principale, allinizio dellariga. Es:@tagInline tagsSi trovano nella
descrizione principale O nelladescrizione 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 awi 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
ej ava. awt . Bas e W n d o wi* @s e e%I e %G sono macroj ava. awt
. Bu t t o n*/ settatec l as s W n d o w e x t e n d s iBas e W n d
o w { . . . } i automagicamente dai sistemi di versioning (CVS,
SVN, ...) 13. @paramDescrive i parametri dei metodiname DEVE
essere/* uguale al nome * Th i s me t h o d wi l l s ayhel 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 yrgr e e t i ng.*/p u b l i c St ri
ngHe 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. @returnDescrive i valori di ritornoDocumentare 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, @exceptionUno 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 notPossibile
anche perc o n t ai n a * p ar s ab l e le unchecked< c od e
> l ong< /c od e > . */ exceptionsp 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. @seeAggiuge link ipertestuali
aggiuntivi /* * * ... * @s ee < aVarianti 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 e q u al s */ label p u b l i c vo i d me t
h o d ( ) {. . . }@see package.class#member label 17. @link
package.class#memberSimile al precedente, ma in versione inlineNon
genera/* * cross-reference* Re t u r n s t h e c o mp o n e n t att
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
ali 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 ft h e { @l i nk L i s t }i
n t e r f ac e ) . 18. @inheritDocPer 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 @throwsQuando 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 Java5)Doclet Permettono di generare
vari di tipi di documento (es: PDF)Taglet Permettono di usare tag
personalizzatiUMLGraph Permettono di generare grafici
UMLAnnotations Documentazione pi raffinata. 21. Integrato in
Netbeans!Scrivere la documentazioneSi noti che il commento
allinterno di un Jdoc formattato automaticamente!Selezionare Run
> Generate JavadocIl browser si apre sulla documentazioneLa
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
documentazioneUsate JavaDocCommentateAggiornateVivete felici 23.
BibliografiaAndrea Gallidabino, Florian Gysin Intro to TdocMADS
Group - Departamento de Computacion Documentando con Javadoc,
IntroduccionDocumentazione ufficiale Java
http://docs.oracle.comQuesto documento dotato di licenza
CreativeCommon BY- SA
3.0http://creativecommons.org/licenses/by-sa/3.0/deed.it
