Introduzione a java doc

2,519 views

Published on

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

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
2,519
On SlideShare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
20
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Introduzione a java doc

  1. 1. javaDoc ovvero... Documentazione semplice Prof. Marcello Missiroli marcello.missiroli@gmail.com   
  2. 2. Scopo Scrivere codice è complicato Mantenere codice altrui..di più!   
  3. 3. Scopo Scrivere codice è complicato Mantenere codice altrui..di più! Supportiamo gli sviluppatori con la documentazione Manutenzione Riutilizzo   
  4. 4. Cosa documentare? Obbligatorio (con Javadoc): Classi Package Costruttori, metodi e attibuti Vivamente consigliato ( con /* */ e // ) Snippets poco chiari Algoritmi Cicli   
  5. 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. 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. 7. Sintassi semplice Basta premettere un testo con un particolare formato al codice da commentare. /** * * Descrizione principale (testo / HTML) * * * Tags (testo / HTML) * * */   
  8. 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. 9. Risultato   
  10. 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 luso della 3° persona Iniziare con un verbo la descrizione dei metodi Omettere il soggetto quando è ovvio   
  11. 11. I tag Javadoc Case sensitive! Sono di due tipi: “block tag” e “inline tag” Block tags Si trovano nella descrizione principale, allinizio della riga. Es: @tag Inline tags Si trovano nella descrizione principale O nella descrizione dei block tag. Es:  {@tag}  
  12. 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. 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. 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. 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. 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. 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. 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. 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. 20. JavaDoc avanzato (da Java5) 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. 21. Integrato in Netbeans! Scrivere la documentazione Si noti che il commento allinterno 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. 22. Riassumendo... Supportate gli sviluppatori con la documentazione Usate JavaDoc Commentate Aggiornate Vivete felici   
  23. 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   

×