javadoc în Java

/**
 * Descrierea metodei.
 *
 * @param pret prețul fără TVA
 * @return prețul cu TVA
 * @throws IllegalArgumentException dacă prețul e negativ
 */
public static double cuTva(double pret) { ... }

$ javadoc -d docs src/ro/dexblog/bani/*.java

Ce face javadoc

Un comentariu care începe cu /** (două stele), pus imediat înaintea unei declarații, este un comentariu de documentație. Prima propoziție devine rezumatul, iar etichetele descriu detaliile: @param (fiecare parametru), @return, @throws, @see, @since, @author, @deprecated. În text poți folosi {@code ...} pentru cod și {@link Clasa#metoda} pentru legături.

Comanda javadoc -d docs fisiere.java generează un site HTML (la fel ca documentația oficială Java), cu index, căutare și pagini pentru fiecare clasă. Documentează implicit membrii public și protected și avertizează pentru cei fără comentariu. Din Java 23 poți scrie documentația și în Markdown, cu linii care încep cu ///.

Comentariile de documentație nu schimbă felul în care rulează programul, dar mediile de dezvoltare le afișează când treci cu mouse-ul peste o metodă. Cu javac -Xlint:all, un comentariu /** care nu este urmat de o declarație dă avertismentul [dangling-doc-comments].

Exemple

Exemplul 1: O clasă documentată

Clasa, constanta și metoda cuTva au comentarii de documentație. Programul rulează normal; comentariile sunt ignorate la execuție.

/**
 * Calcule simple cu prețuri și TVA, în lei.
 *
 * @author Ana Popescu
 * @since 1.0
 */
final class Calculator {

    /** Cota standard de TVA din România (21%). */
    static final double TVA = 0.21;

    private Calculator() {
    }

    /**
     * Calculează prețul final, cu TVA inclus.
     *
     * @param pret prețul fără TVA, în lei; trebuie să fie pozitiv
     * @return prețul cu TVA, rotunjit la două zecimale
     * @throws IllegalArgumentException dacă {@code pret} este negativ
     */
    static double cuTva(double pret) {
        if (pret < 0) {
            throw new IllegalArgumentException("preț negativ");
        }
        return Math.round(pret * (1 + TVA) * 100) / 100.0;
    }
}

/** Punctul de pornire al exemplului. */
public class Main {
    /**
     * Afișează câteva prețuri cu TVA.
     *
     * @param args nefolosite
     */
    public static void main(String[] args) {
        for (double pret : new double[] {10, 99.99, 1250}) {
            System.out.println(pret + " lei -> " + Calculator.cuTva(pret) + " lei cu TVA");
        }
    }
}

Rezultat

10.0 lei -> 12.1 lei cu TVA
99.99 lei -> 120.99 lei cu TVA
1250.0 lei -> 1512.5 lei cu TVA

Exemplul 2: Generarea documentației HTML

Aceeași clasă, publică și pusă în pachetul ro.dexblog.bani, plus o metodă reducere fără comentariu. javadoc creează directorul docs/ cu paginile HTML și avertizează pentru metoda nedocumentată (warning: no comment). Opțiunea -quiet ar păstra doar avertismentele.

// ro/dexblog/bani/Calculator.java (fragment)
package ro.dexblog.bani;

public final class Calculator {
    // ... ca mai sus, cu public pe clasă și pe membri ...

    public static double reducere(double pret, int procent) {
        return pret * (100 - procent) / 100;
    }
}

Rezultat în terminal

$ javadoc -d docs ro/dexblog/bani/Calculator.java
Loading source file ro/dexblog/bani/Calculator.java...
Constructing Javadoc information...
Creating destination directory: "docs/"
Building index for all the packages and classes...
Standard Doclet version 27
Building tree for all the packages and classes...
Generating docs/ro/dexblog/bani/Calculator.html...
ro/dexblog/bani/Calculator.java:31: warning: no comment
    public static double reducere(double pret, int procent) {
                         ^
Generating docs/ro/dexblog/bani/package-summary.html...
Generating docs/ro/dexblog/bani/package-tree.html...
Generating docs/constant-values.html...
Generating docs/overview-tree.html...
Generating docs/allclasses-index.html...
Building index for all classes...
Generating docs/allpackages-index.html...
Generating docs/index-all.html...
Generating docs/search.html...
Generating docs/index.html...
Generating docs/help-doc.html...
1 warning

Greșeli frecvente

• Folosești /* ... */ (o singură stea): este un comentariu obișnuit și javadoc îl ignoră.
• Pui comentariul de documentație departe de declarație sau după adnotări și cod: nu mai este asociat cu nimic, iar javac -Xlint:all dă [dangling-doc-comments].
• Scrii @param pentru un parametru care nu există (după o redenumire): javadoc raportează error: @param name not found.

Comenzi înrudite

• javac: javac este compilatorul Java: transformă fișierele .java în fișiere .class (bytecode) și raportează erorile și avertismentele.
• Adnotări (@Override, @Deprecated, @FunctionalInterface...): Adnotările (@Nume) adaugă informații despre cod pentru compilator, unelte sau program: @Override, @Deprecated, @SuppressWarnings, @FunctionalInterface.
• jar: jar împachetează clasele compilate (și resursele) într-o singură arhivă .jar, care poate fi distribuită și rulată cu java -jar.