Abbiamo consultato spesso la Java API (as esempio, la API
della classe String [locale,
Medialab,
Sun]):
vediamo le informazioni che vengono fornite sulla classe in generale
e su singoli membri (variabili/costruttori/metodi).
Due domande naturali:
- Come è stata generata questa documentazione?
- Cosa dobbiamo fare per ottenere una analoga documentazione delle
nostre classi?
La documentazione vista è generata con il programma javadoc (scritto in Java e
disponibile nella distribuzione standard),
che permette di estrarre automaticamente documentazione HTML da
programmi Java opportunamente commentati.
Alcune informazioni possono essere generate semplicemente analizzando
il codice, altre invece vengono estratte da commenti scritti secondo
uno stile opportuno.
Vediamo un esempio: la classe LinkedList
e la sua documentazione generata con javadoc.
Si noti la struttura dei commenti (devono iniziare con "/**") e le parole chiave che
contengono
(come @return, @param, ecc.).
Naturamente la generazione e consultazione della documentazione
del codice è ben integrata in Eclipse
(lo vedremo con una piccola demo).
Manuale online di javadoc:
http://java.sun.com/j2se/javadoc/writingdoccomments/
Attenzione: Per il progetto finale,
una documentazione completa del codice in questo stile sarà un
requisito
esplicito.
