Tutorial Java 6 – #2.1 Cum sa definesti comentarii JavaDoc

In programare este important sa documentezi codul sursa pentru

  • a avea o imagine clara a proiectelor Java complexe cu multe clase
  • a putea, mai tarziu, sa intelegi ce s-a facut astfel incat sa poti modifica, adauga sau sterge.

Pentru aplicatiile Java, documentatia este furnizata de obicei in format HTML sub forma de arhive sau fisiere .chm. Pentru eficienta documentatia codului sursa, JavaDoc, este generat automat pe baza comentariilor din codul sursa de un utilitar, javadoc.exe, inclus in JDK (Java Development Kit).

Am vazut in Tutorial Java 6 – #2 Concepte de baza (alte topicuri prezentate in acest tutorial pot fi gasite in Tutorial Java 6 – Continut) cum se scriu comentariile in Java, insa pentru a genera documentatie de tip JavaDoc, comentariile din cod trebuie definite dupa anumite reguli:

  • blocurile de comentarii incluse in documentatie incep cu /** ;
  • blocurile de comentarii incluse in documentatie se termina cu */ ;
  • liniile din comentarii incep, prin conventie, cu *;
  • la generarea automata a documentatiei, * sau spatiile din inceputul comentariului sunt ignorate;
  • comentariile utilizate la generarea documentatiei sunt asociate metodelor sau claselor;
  • deoarece documentatia JavaDoc este in format HTML, in comentarii pot fi inserate tag-uri HTML pentru a formata continutul (de exemplu <br> pentru a trece pe linia urmatoare)
  • exista o serie speciala de tag-uri pentru atribute speciale ale clasei sau metodei
Tag JavaDoc Semnificatie Descrie
@see Nume clasa asociata Clasa, metoda
@author Autor Clasa
@version Versiune Clasa
@param Parametrii intrare Metoda
@return Valoare returnata Metoda
@exception Exceptie generata Metoda
@throws Exceptie generata Metoda
@deprecated Definineste elementul ca fiind invechit Clasa, metoda
@since Versiunea API-ului la care elementul a fost adaugat Clasa, metoda

Comentariile de tip @deprecated sunt folosite si de compilator pentru a genera avertismente. Acest concept este intalnit si la adnotari (Java annotations) instroduse de Java 5.

Pentru eficienta, documentatia JavaDoc este generata automat din IDE-ul folosit, NetBeans (click-dreapta pe numele proiectului si apoi se alege Generate Javadoc) sau Eclipse (Tutorial Java 6 – #2.2 Cum sa generezi JavaDoc in Eclipse sau NetBeans), fara a fi nevoit sa folosesti javadoc.exe din linia de comanda.

Pentru codul sursa Java din MyClass.java

/**
 * 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.println(message);
    }
     /**
     *
     * Exemplu metoda simpla.
     * <br>
     * 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;
    }
}

Prin generarea automata a JavaDoc-ului in NetBeans (click-dreapta pe numele proiectului si apoi se alege Generate Javadoc) sau Eclipse (Tutorial Java 6 – #2.2 Cum sa generezi JavaDoc in Eclipse sau NetBeans) se obtine documentatia JavaDoc a proiectului din exemplu.

Daca pentru dezvoltarea se foloseste Eclipse, acest IDE are facilitati ce permit generarea automata a comentariilor JavaDoc. Daca se considera metoda:

    public int add2(int val1, int val2)
    {
       return val1+val2;
    }

atunci se poate apela optiunea Generate Element Comment (Alt + Shift + J) din categoria Source a meniului. Automat este generat un bloc de comentarii:

    /**
     * @param val1
     * @param val2
     * @return
     */
    public int add2(int val1, int val2)
    {
       return val1+val2;
    }

Alte topicuri prezentate in acest tutorial Java pot fi gasite in Tutorial Java 6 – Continut.