Limbajul Java pune la dispozitia dezvoltatorilor un utilitar special (javadoc) pentru generarea de documentatie pe baza comentariilor introduse in fisierele sursa. Documentatia rezultata este in format HTML si descrie clase, interfete, constructori, metode, etc.
Programatorul poate include comentarii de documentare (doc comments sau comentarii Javadoc) in codul sursa, inaintea declaratiei unei clase, interfete, metode, constructor sau atribut.
Comentariile Javadoc sunt introduse intre sirurile de caractere /** si */. Textul dintr-un astfel de comentariu poate sa fie dispus pe una sau mai multe linii.
In general, un comentariu Javadoc este alcatuit dintr-o descriere principala, care incepe dupa caracterele /**, si o sectiune de tag-uri. Sectiunea de tag-uri incepe cu declaratia primului marcaj special (tag), marcaj care este definit prin utilizarea caracterului @.
Tag-urile reprezinta cuvinte cheie dintr-un comentariu care pot fi procesate de catre utilitarul javadoc. Exista doua tipuri de marcaje speciale: block tags si in-line tags. Pentru a fi interpretate marcajele de tip block trebuie sa apara obligatoriu la inceputul unei linii. Marcajele in-line pot fi pozitionate oriunde in interiorul unui comentariu si au formatul {@tag}.
Principalele marcaje speciale sunt:
@author, {@docRoot}, @deprecated, @exception, {@inheritDoc}, {@link}, {@linkplain}, @param, @return, @see, @serial, @serialData, @serialField, @since, @throws, {@value}, @version.
In continuare vom comenta aplicatia BunVenit.java folosind taguri din lista de mai sus.
/** | |
* Clasa BunVenit exemplifica afisarea unui mesaj de bun venit | |
* | |
* @author airman | |
* @version 1.0 | |
*/ | |
public class BunVenit { | |
/** | |
* @param nume sir de caractere folosit pentru transmiterea numelui | |
* @return returneaza un mesaj de bun venit personalizat | |
* | |
* <pre> | |
* {@code | |
* public static String mesaj(String nume) { | |
* String mesaj = "Bun venit in lumea Java " + nume; | |
* return mesaj; | |
* } | |
* } | |
* </pre> | |
*/ | |
public static String mesaj(String nume) { | |
String mesaj = "Bun venit in lumea Java " + nume; | |
return mesaj; | |
} | |
/** | |
* Metoda main() <br> | |
* Utilizeaza {@link #mesaj(String)} pentru a personaliza mesajul | |
* | |
* @param args tablou care contine parametri din linia de comanda | |
*/ | |
public static void main(String args[]) { | |
System.out.println(mesaj("Popescu Vlad")); | |
} | |
} |
D:\java>javac BunVenit.java D:\java>java BunVenit Bun venit in lumea Java Popescu Vlad
Apelarea utilitarului javadoc pentru fisierul sursa se poate face utilizand urmatoarea sintaxa.
javadoc –author –version –d dir fisier.java
D:\java>javadoc -author -version -d docs BunVenit.java Loading source file BunVenit.java... Constructing Javadoc information... Standard Doclet version 12.0.2 Building tree for all the packages and classes... Generating docs\BunVenit.html... Generating docs\package-summary.html... Generating docs\package-tree.html... Generating docs\constant-values.html... Building index for all the packages and classes... Generating docs\overview-tree.html... Generating docs\deprecated-list.html... Building index for all classes... Generating docs\index-all.html... Building index for all classes... Generating docs\allclasses-index.html... Generating docs\allpackages-index.html... Generating docs\index.html... Generating docs\help-doc.html...
Optiunile –author si –version permit procesarea marcajelor @author si @version in momentul generarii documentatiei.