Utilitarul Javadoc

Documentarea codului surs al unei aplicaii, n general, sau al unei aplicaii Java, n
particular, este absolut necesar, cel puin din dou motive:

pentru a avea o imagine clar a proiectelor complexe, cu multe clase;

pentru a nelege mai trziu ceea ce s-a fcut, astfel nct s se poat efectua modificri
ale proiectelor respective.

Javadoc este o aplicaie (javadoc.exe) inclus n JDK (Java Development Kit),

care permite generarea documentaiei API n format HTML, pornind de la comentariile de
documentaie din fiierele surs:
/**
... comentarii de documentaie ...
*/
Observaii:
1. API = Application Programming Interface este un termen care desemneaz o interfa
pentru programarea de aplicaii. De obicei este vorba despre interfaa dintre programele de
aplicaie i sistemul de operare, care stabilete n amnunt modul n care programele de aplicaie
pot accesa (apela) serviciile sistemului de operare sub care ruleaz.
n cazul nostru, documentaia API reprezint o descriere n format HTML a claselor,
interfeelor, metodelor, atributelor etc. din cadrul pachetelor Java, preciznd astfel rolul acestora
i modul n care pot fi utilizate de programator.
2. HTML = HyperText Markup Language este un limbaj de marcare utilizat pentru
crearea paginilor web ce pot fi afiate de un browser (sau navigator).
Paginile (documentele) HTML sunt formate din etichete (sau tag-uri) i au extensia
.html sau .htm.
n marea lor majoritate, aceste tag-uri sunt pereche, unul de deschidere <tag> i altul de
nchidere </tag>.
HTML nu este un limbaj case sensitiv (nu face deosebirea ntre litere mici i mari).
Pentru a se genera documentaie cu utilitarul javadoc, comentariile din cod trebuie
definite dup anumite reguli:

blocurile de comentarii incluse n documentaie ncep cu /** ;

blocurile de comentarii incluse n documentaie se termin cu */;
liniile din comentarii ncep, prin conventie, cu *;
la generarea automat a documentaiei, * sau spaiile de la nceputul comentariului sunt
ignorate;
comentariile utilizate la generarea documentaiei sunt asociate metodelor sau claselor;
deoarece documentaia care se obine este n format HTML, n comentarii pot fi inserate
tag-uri HTML pentru a formata coninutul (de exemplu: <br> pentru a trece pe linia
urmtoare) .

Etichete (tag-uri) javadoc

n cadrul comentariilor de documentaie din interiorul fiierelor surs, javadoc permite
utilizarea unor etichete (tag-uri) speciale.
Aceste tag-uri ncep cu caracterul @.
Tag JavaDoc
@see
@author
@version
@param
@return
@exception
@throws
@deprecated
@since

Semnificaie
Nume clas asociat
Autor
Versiune
Parametrii de intrare
Valoare returnat
Excepie generat
Excepie generat
Definete elementul ca fiind
nvechit
Versiunea API la care
elementul a fost adugat

Ce descrie
Clasa, metoda
Clasa
Clasa
Metoda
Metoda
Metoda
Metoda
Clasa, metoda
Clasa, metoda

Comentariile de tip @deprecated sunt folosite i de compilator pentru a genera

avertismente. Acest concept este ntlnit i la adnotri (Java annotations) introduse ncepnd cu
Java 5.

Descrierea utilitarului javadoc

Apelul utilitarului javadoc

Opiunile utilitarului javadoc

Exemplu.
Vom considera urmtorul exemplu de clas Java cu comentarii JavaDoc:
/**
* Exemplu clasa in Java
* Clasa exemplifica modul in care pot fi scrise comentarii pe baza
* carora sa se genereze documentatie de tip JavaDoc
*
* @author Catalin
* @version 2.00, 23 Dec 2010
*/
public class MyClass {
/**
*
* Exemplu metoda simpla.
*
* Metoda afiseaza la consola un mesaj primit ca parametru.
*
* @param message variabila de tip String ce va fi afisata
* @see MyClass
* @deprecated
* @since version 1.00
*/
public void MyMethod(String message)
{
System.out.printf(message);
}
/**
*
* Exemplu metoda simpla.
* Metoda afiseaza la consola un mesaj primit ca parametru
*
* @param message variabila de tip String ce va fi afisata
* @since version 1.00
*/
public void printMessage(String message)
{
System.out.printf(message);
}
/**
*
* Exemplu metoda simpla.
*
* Metoda aduna 2 numere si returneaza valoarea lor.
*
* @param val1 primul numar
* @param val2 al doilea numar
* @return suma dintre val1 si val2
* @since version 2.00
*/
public int add(int val1, int val2)
{
return val1+val2;

}
}

Apelarea n mod linie de comand a utilitarului javadoc

pentru generarea documentaiei:
...> javadoc -d doc MyClass.java
Opiunea -d doc precizeaz c documentaia se va genera n folderul doc.
+
6

Generare documentaie n NetBeans i Eclipse

Deoarece este mai eficient s se dezvolte proiecte Java complexe ntr-un mediu integrat
(IDE = Integrated Development Environment) ca NetBeans sau Eclipse, documentatia JavaDoc
poate fi generat automat tot din aceste medii.
Pentru a exemplifica modul de creare a documentaiei JavaDoc n cele 2 IDE-uri,
NetBeans sau Eclipse, vom considera exemplul anterior de clas Java.
A. Generare JavaDoc n NetBeans
1. Se deschide proiectul n NetBeans
2. n fereastra Projects, prin click-dreapta pe numele proiectului se selecteaz Generate
JavaDoc. O alt posibilitate este prin opiunea Run > Generate JavaDoc

3. Proiectul HTML aferent documentaiei JavaDoc va fi generat automat n directorul

proiectului Java, n subdirectorul dist/javadoc i va avea forma din documentaia JavaDoc a
proiectului din exemplu.

B. Generare JavaDoc n Eclipse Helios

1. Se deschide proiectul n Eclipse
2. Se alege opiunea Project > Generate JavaDoc

3. La pasul 1 se fac setri cu privire la:

3.1. calea ctre utilitarul javadoc.exe din JDK;
3.2. resursele din proiect pentru care se genereaz JavaDoc
3.3. clasele i metodele cu o vizibilitate particular
3.4. locaia n care va fi generat documentaia (implicit n directorul doc din locaia
proiectului Java)

4. La pasul 2 se fac setri cu privire la:

4.1. structura documentaiei
4.2. tag-urile JavaDoc luate n considerare
4.3. generare de documentaie i pentru alte resurse (API, pachete, proiecte) folosite n
proiect
4.4. o alt foaie de stil CSS pentru design-ul documentaiei

Observaie.
CSS = Cascading Style Sheets este un limbaj care permite formatarea elementelor unui
document HTML.
Stilurile se pot ataa elementelor HTML prin intermediul unor fiiere externe sau, n
cadrul documentului, prin elementul <style> i/sau atributul style.

5. La ultimul pas se fac setri cu privire la salvarea configurrilor ntr-un script Ant care
s fie folosit n viitor la generarea JavaDoc-ului.

Observaie.
Ant este o aplicaie gen make care permite automatizarea diferitelor operaii, cum ar fi
compilarea unei aplicaii i pregtirea ei pentru a fi distribuit sau livrat. (Este o unealt
similar utilitarului make utilizat la dezvoltarea aplicaiilor scrise n limbajul C.)
Ant este foarte util n cazul aplicaiilor Java complexe care necesit multe operaii pentru
a fi transformate din cod surs, n cod binar gata de a fi rulat.
Apache Ant este o unealt open-source de dezvoltare software scris n ntregime n
Java.
Spre deosebire de make care nva s execute noi aciuni prin intermediul comenzilor
shell-ului (command.com, bash), Ant se poate extinde scriind noi clase Java. Fiierele de
configurare se bazeaza pe XML.

6. Dup terminarea setrilor, documentaia va fi generat automat.

10