Documentarea codului sursa Java se face prin proiecte JavaDoc, ce reprezinta o colectie de pagini HTML in care sunt descrise clasele si metodele din cod. Pentru a genera documentatia JavaDoc se foloseste un instrument din JDK, javadoc.exe, si comentariile din cod se scriu dupa reguli stricte (Tutorial Java 6 – #2.1 Cum sa definesti comentarii JavaDoc). Deoarece este mai eficient sa dezvolti proiecte Java complexe intr-un IDE (Integrated Development Environment) ca NetBeans sau Eclipse, documentatia JavaDoc poate fi generata automat tot din aceste medii.

Acest topic face parte dintr-un tutorial Java 6 accesibil prin Tutorial Java 6 – Continut.

Pentru a exemplifica modul de creare a documentatiei JavaDoc in cele 2 IDE-uri, NetBeans sau Eclipse, vom considera urmatorul exemplu de clasa 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;
    }
}

Generare JavaDoc in Netbeans

1. Se deschide proiectul in NetBeans

2. In fereastra Projects, prin click-dreapta pe numele proiectului se selecteaza Generate JavaDoc; O alta posibilitate este prin optiunea Run –> Generate JavaDoc

3. Proiectul HTML aferent documentatiei JavaDoc este generat automat in directorul proiectului Java in subdirectorul dist/javadoc si va avea forma din documentatia JavaDoc a proiectului din exemplu.

Generare JavaDoc in Eclipse Helios

1. Se deschide proiectul in Eclipse

2. Se alege optiunea Project –> Generate JavaDoc

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

3.1 calea catre instrumentule javadoc.exe din JDK;

3.2 resursele din proiect pentru care se genereaza JavaDoc

3.3 clasele si metodele cu o vizibilitate particulara

3.4 locatia in care va fi generata documentatia (implicit in directorul doc din locatia proiectului Java)

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

4.1structura documentatiei

4.2 tag-urile JavaDoc luate in considerare

4.3 genereare de documentatie si pentru alte resurse (API, librarii,proiecte) folosite in proiect

4.4 o alta foaie de stil CSS pentru design-ul documentatiei

5. La ultimul pas se fac setari cu privire la salvarea setarilor intr-un script Ant care sa fie folosit in viitor la generarea JavaDoc-ului.

6. Dupa terminarea setarilor, documentatia este generata automat si va avea forma din documentatia JavaDoc a proiectului din exemplu.

Acest topic face parte dintr-un tutorial Java 6 accesibil prin Tutorial Java 6 – Continut.