Ingegneria del Software: gruppo 9 Progetto Doclet -  JavaToXmiuml DOCLET

Le Basi

Un Semplice Esempio

Tag di Javadoc: Tag standard e personalizzati

Opzioni sulla linea di comando

Doclet Api

Bibliografia

I passi base da seguire nella creazione di una doclet sono:
 

1. Scrivere il programma JAVA che costituisce il doclet. Il programma deve importare com.sun.javadoc.* in modo da utilizzare le doclet API. Il punto d'entrata del tuo programma è una classe con il metodo public static boolean start e che prende RootDoc come parametro.
2. Compilare il doclet con un compilatore JAVA
3. Eseguire Javadoc usando l'opzione -doclet <TuaDoclet> per produrre l'output specificato nella tua doclet.

Il Package com.sun.javadoc consiste delle interfacce che definiscono i doclet API, e il file lib/tools.jar e il file del JDK che contiene queste interfacce oltre ai Package privati  con le classi che implementano le interfacce. Il tools.jar contiene anche le classi che implementano il doclet standard.

import com.sun.javadoc.*;
public class ListClass {
    public static boolean start(RootDoc root) {
        ClassDoc[] classes = root.classes();
        for (int i = 0; i < classes.length; ++i) {
           System.out.println(classes[i]);
        }
        return true;
    }
}

Questa doclet prende le classi su cui Javadoc sta operando e stampa il suo nome sull' output standard.

La prima cosa da notare su una doclet è che essa importa il Package com.sun.javadoc in modo da usare i doclet API. Come TUTTI i doclet ha il suo punto di ingresso nel metodopublic static boolean start.
Il metodo start prende RootDoc come parametro. Questo parametro riporta informazioni circa ogni opzione specificata nella linea di comando con cui è stato lanciato Javadoc, e anche circa le classi e i package su cui lavora Javadoc.

RootDoc definisce un metodo classes che ritorna un array di ClassDoc in cui ogni elemento rappresenta una classe che Javadoc ha scansionato. Il for cicla per stamapare i nomi di ogni classe nell'array.

Per lanciare questa doclet, prima la si deve compilare. Si può compilare con il compilatore JDK? javac, con una riga tipo questa:

javac -classpath C:\jdk1.2\lib\tools.jar ListClass.java

a questo punto poniamo di voler lanciare il nostro doclet sul file MiaClasse.java, userò il comando:

% javadoc -doclet ListClass -classpath C:\jdk1.2\lib\tools.jar MiaClasse.java

L'output che avremo sarà quindi la stringa "MaiClasse". Si noti come questo comando richieda tools.jar nel classpath.

I commenti di documentazione sono associati alla dichiarazione della classe, variabile o metodo che essi precedono.

All'interno di questi commenti e' poi possibile specificare tag speciali, che cominciano tutti con il carattere @. Il doclet standard di java (ovvero javadoc invocato senza l'opzione -doclet), che genera un file di documentazione in formato HTML, riconosce un certo numero di tag all'interno di un commento di documentazione. Ad esempio:

@see classname
Se specificato nel sorgente prima di una classe, metodo o attributo, questo tag aggiunge al file HTML una entry "See Also:" che contiene un hyperlink alla classe specificata.

@return description
Aggiunge una sezione "Returns:" contenente la descrizione specificata.E' semanticamente corretto utilizzarlo prima di una definizione di un metodo.

Questi (e altri) sono i tag riconosciuti dal doclet standard: tuttavia ogni doclet puo' riconoscere tag personalizzati. Supponiamo per esempio di voler specificare in un file sorgente java, tramite un numero, l'importanza di un metodo(es. 3 = metodo obbligatorio, 2 = importante, 1 = ausiliario). Possiamo allo scopo definire un tag @importance. Successivamente il nostro doclet per reperire l'informazione sull'importanza dovra':

• ottenere i metodi di una specifica classe tramite il metodo methods() di ClassDoc, che restutuisce un array di istanze di tipo MethodDoc;
• richiamare su ogni classe MethodDoc cosi' ottenuta il metodo tags("@importance") (che e' un metodo della classe Doc, superclasse di ClassDoc, MethodDoc e FieldDoc) che ritorna un array di oggetti Tag uno per ogni tag @importance contenuto nei commenti di documentazione che precedono il metodo in questione;
• chiamare il metodo text() della classe Tag per ottenere il testo del tag.

• -classpath path: specifica il percorso che javadoc utilizza per cercare il package o i file specificati sulla linea di comando;
• -private: dice a javadoc di considerare tutte le classi, metodi e attributi (per default vengono esaminate solo le classi, i metodi e gli attributi pubblici);
• -docletpath path1,...,pathn: specifica uno o piu' directory contenenti delle doclet;
• -doclet doclelClass: indica a Javadoc il nome della classe del doclet.

Fino a questo momento si e' utilizzato impropriamente il termine classe: in realta' le Doclet API utilizzano soltanto interfaccie (eccezion fatta per la classe astratta Doclet). In effetti non c'e' alcun motivo in una doclet di creare una nuova istanza, tramite new, di una classe, di un metodo o di un attributo: sono le API che tramite metodi appositi (vedi per esempio RootDoc.classes[]) forniscono le istanze opportune delle interfaccie.
Utilizzando soltanto interfaccie, le Doclet API possono sfruttare l'ereditarieta' multipla.

Ecco il diagramma delle interfaccie:

Nel seguito, per le interfaccie che riteniamo piu' importanti, riportiamo i metodi piu' significativi. La semantica si puo' facilmente evincere dal nome, dal valore di ritorno e dalla classe di appartenenza dei metodi stessi:ad esempio, ClassDoc.constructors() ritorna tutti i costruttori della classe specificata.

Per maggiori dettagli, si veda la documentazione ufficiale della SUN (scritta utilizzando Javadoc standard richiamato sul package com.sun.javadoc!) all'indirizzo www.sun.com.

1. ClassDoc
 
• ConstructorDoc[] constructors()
• FieldDoc[] fields()
• ClassDoc[] interfaces()
• boolean isAbstract()
• MethodDoc[] methods()
2. ConstructorDoc
 
• String qualifiedName()
3. Doc
 
• boolean isClass(), isConstructor(), isField(), isMethod()
• Tag[] tags()
• Tag[] tags(String tagname)
4. ExecutableMemberDoc
 
• boolean isNative(), isSynchronized()
• Parameter[] parameters()
5. FieldDoc
 
• Type type()
6. MethodDoc
 
• boolean isAbstract()
• Type returnType()
7. Parameter
 
• String name()
• Type type()
8. ProgramElementDoc
 
• boolean isFinal(), isPackagePrivate(), isPrivate(),isProtected(), isPublic(), isStatic()
• String qualifiedName():nome esteso dell'elemento (es. di una classe, ritorna package.nomeclasse)
9. RootDoc
 
• ClassDoc[] classes()
10. Tag
 
• String name()
• String text()
11. Type
 
• ClassDoc asClassDoc():ritorna null se il tipo e' primitivo
• String dimension():ritorna la dimensione (es. [] per gli array)
• String typeName():ritorna il nome del tipo senza dimensione

On-line
 

Titolo	Autore	Sito	Breve descrizione
Home Sun	Sun	http://www.sun.com	Sito principale della Sun
Home Java	Sun	http://java.sun.com	Sito principale di Java
Home documentazione JDK 1.2	Sun	http://java.sun.com/products/jdk/1.2/docs/index.html	Sito Ufficile di documentazione del JDK 1.2
Home documentazione Javadoc	Sun	http://java.sun.com/products/jdk/javadoc/	Sito Ufficiale di documentazione di Javadoc
Java Discussion Forums - Javadoc	Autori Vari	http://forum.java.sun.com/forum?folderBy @220.cLfiaANdlCH^0@.ee76880!skip=24	Forum di discussione del JDC, occorre essere iscritti, ma l'iscrizione è FREE
Javadoc FAQ	Autori Vari	http://java.sun.com/products/jdk/javadoc/faq.html
Sun Developer Connection	Sun	http://www.sun.com/developers/italian/	Servizi per sviluppatori della Sun

 

Pagina Realizzata dal Gruppo 9 / Corso di Ingegneria del Software / Dipartimento di informatica / Università di Bologna