4.3. 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.
- 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.
/**
* 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.
```java
/**
* @param name der Name des Benutzers
*/
```
- `@return`: Beschreibt den Rückgabewert der Methode.
```java
/**
* @return die Länge des Strings
*/
```
- `@throws` oder `@exception`: Gibt an, welche Ausnahme geworfen werden kann.
```java
/**
* @throws IllegalArgumentException wenn der Eingabewert null ist
*/
```
- `@see`: Verweist auf eine verwandte Klasse oder Methode.
```java
/**
* @see java.util.Objects#requireNonNull(Object)
*/
```
- `@since`: Gibt an, seit welcher Version das Element existiert.
```java
/**
* @since 1.4
*/
```
- `@deprecated`: Markiert ein Element als veraltet.
```java
/**
* @deprecated Verwende stattdessen doSomethingNew().
*/
```
- `@author`: Gibt den Autor des Codes an.
```java
/**
* @author Max Mustermann
*/
```
- `@version`: Gibt die Version des Codes an.
```java
/**
* @version 1.2.0
*/
```
Diese Tags können einzeln oder kombiniert in JavaDoc-Kommentaren verwendet werden, um zusätzliche Informationen bereitzustellen.