Java-documentatiecommentaar: Javadoc en commentaartypes beheersen

Drie soorten commentaar in Java

Wat is Javadoc?

Javadoc is een tool in de JDK die HTML-documentatie genereert uit broncode die voorzien is van documentatiecommentaar (doc comments).

Basissjabloon

/**
 * Korte beschrijving van de klasse.
 * <p>
 * Uitgebreide uitleg, eventueel met HTML-tags.
 *
 * @author Jouw Naam
 * @version 1.0
 * @since 2024-01-15
 */
public class MijnKlasse {
    // ...
}

Belangrijke Javadoc-tags

Volledig voorbeeld

import java.io.*;

/**
 * <h1>Twee getallen optellen</h1>
 * De klasse {@code AddNum} telt twee integers op en print het resultaat.
 * <p>
 * <b>Let op:</b> Goede documentatie verbetert onderhoudbaarheid.
 *
 * @author Zara Ali
 * @version 1.0
 * @since 2014-03-31
 */
public class AddNum {

    /**
     * Tel twee integers op.
     *
     * @param numA eerste term
     * @param numB tweede term
     * @return de som van numA en numB
     */
    public int addNum(int numA, int numB) {
        return numA + numB;
    }

    /**
     * Hoofdprogramma.
     *
     * @param args niet gebruikt
     * @throws IOException bij invoerfout
     * @see IOException
     */
    public static void main(String[] args) throws IOException {
        AddNum obj = new AddNum();
        int sum = obj.addNum(10, 20);
        System.out.println("Som van 10 en 20 is: " + sum);
    }
}

Javadoc uitvoeren

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Generating AddNum.html...
Generating index.html...
... (meer bestanden)

De gegenereerde HTML-bestanden bevatten de volledige documentatie met navigatieframes, index, hiërarchie, etc. Voor een mooiere stylesheet download je stylesheet.css van Oracle's JDK 7 documentatie.

Tips

• Schrijf duidelijke, beknopte eerste zin (samenvatting)
• Gebruik HTML-sparend voor opmaak
• Documenteer alle publieke API's
• Houd commentaar actueel bij codewijzigingen
• Gebruik {@code} voor code-fragmenten in lopende tekst