4.3. JavaDoc

Warum JavaDoc?

JavaDoc ist ein Werkzeug von Oracle, das automatisch HTML-Dokumentationen aus Java-Quellcode generiert. Es hilft dabei, den Code verständlicher und wartbarer zu machen – sowohl für andere Entwickler als auch für einen selbst. Eine gute Dokumentation verbessert die Zusammenarbeit im Team, erleichtert das Onboarding neuer Entwickler und unterstützt externe Nutzer von Bibliotheken oder APIs.

Was sollte dokumentiert werden?

Klassen: Zweck und Verwendung der Klasse.
Methoden: Beschreibung der Funktion, Parameter, Rückgabewerte und mögliche Exceptions.
Konstruktoren: Wann und wie sie verwendet werden sollen.
Felder (optional): Besonders, wenn sie öffentlich sind oder eine spezielle Bedeutung haben.
Besonderheiten: Hinweise auf Seiteneffekte, Thread-Sicherheit, Performance oder Einschränkungen.

Beispielklasse mit JavaDoc

/**
 * Eine Utility-Klasse zum Berechnen mathematischer Operationen.
 */
public class MathUtils {

    /**
     * Addiert zwei ganze Zahlen.
     *
     * @param a der erste Summand
     * @param b der zweite Summand
     * @return die Summe von a und b
     */
    public static int add(int a, int b) {
        return a + b;
    }

    /**
     * Subtrahiert eine ganze Zahl von einer anderen.
     *
     * @param a der Minuend
     * @param b der Subtrahend
     * @return die Differenz von a und b
     */
    public static int subtract(int a, int b) {
        return a - b;
    }

    /**
     * Berechnet den Mittelwert zweier Zahlen.
     *
     * @param a die erste Zahl
     * @param b die zweite Zahl
     * @return der Durchschnitt von a und b als double
     */
    public static double average(int a, int b) {
        return (a + b) / 2.0;
    }
}

Übersicht über häufige JavaDoc-Tags

Neben den Grundelementen wie @param und @return gibt es weitere nützliche Tags, die JavaDoc unterstützt:

@param: Beschreibt einen Methodenparameter.

/**
 * @param name der Name des Benutzers
 */

@return: Beschreibt den Rückgabewert der Methode.
```
/**
 * @return die Länge des Strings
 */
```

@throws oder @exception: Gibt an, welche Ausnahme geworfen werden kann.

/**
 * @throws IllegalArgumentException wenn der Eingabewert null ist
 */

@see: Verweist auf eine verwandte Klasse oder Methode.

/**
 * @see java.util.Objects#requireNonNull(Object)
 */

@since: Gibt an, seit welcher Version das Element existiert.
```
/**
 * @since 1.4
 */
```

@deprecated: Markiert ein Element als veraltet.

/**
 * @deprecated Verwende stattdessen doSomethingNew().
 */

@author: Gibt den Autor des Codes an.
```
/**
 * @author Max Mustermann
 */
```
@version: Gibt die Version des Codes an.
```
/**
 * @version 1.2.0
 */
```
@author und @version: Herkunftsangaben. In Git-Projekten oft verzichtbar, weil die Historie das genauer abbildet.

Diese Tags können einzeln oder kombiniert in JavaDoc-Kommentaren verwendet werden.