Einführung in Javadoc

1. Übersicht

Eine gute API-Dokumentation ist einer der vielen Faktoren, die zum Gesamterfolg eines Softwareprojekts beitragen.

Glücklicherweise bieten alle modernen Versionen des JDK das Javadoc-Tool - zum Generieren von API-Dokumentation aus Kommentaren im Quellcode.

Voraussetzungen:

  1. JDK 1.4 (JDK 7+ wird für die neueste Version des Maven Javadoc-Plugins empfohlen)
  2. Der der Umgebungsvariablen PATH hinzugefügte Ordner JDK / bin
  3. (Optional) eine IDE mit integrierten Tools

2. Javadoc-Kommentare

Beginnen wir mit Kommentaren.

Die Struktur der Javadoc-Kommentare sieht einem normalen mehrzeiligen Kommentar sehr ähnlich , aber der Hauptunterschied ist das zusätzliche Sternchen am Anfang:

// This is a single line comment /* * This is a regular multi-line comment */ /** * This is a Javadoc */

Kommentare im Javadoc-Stil können auch HTML-Tags enthalten.

2.1. Javadoc-Format

Javadoc-Kommentare können über jeder Klasse, Methode oder jedem Feld platziert werden, die wir dokumentieren möchten.

Diese Kommentare bestehen normalerweise aus zwei Abschnitten:

  1. Die Beschreibung dessen, was wir kommentieren
  2. Die eigenständigen Block-Tags (gekennzeichnet mit dem Symbol „ @ “), die bestimmte Metadaten beschreiben

In unserem Beispiel werden einige der gebräuchlichsten Block-Tags verwendet. Eine vollständige Liste der Block-Tags finden Sie im Referenzhandbuch.

2.2. Javadoc auf Klassenebene

Werfen wir einen Blick darauf, wie ein Javadoc-Kommentar auf Klassenebene aussehen würde:

/** * Hero is the main entity we'll be using to . . . * * Please see the {@link com.baeldung.javadoc.Person} class for true identity * @author Captain America * */ public class SuperHero extends Person { // fields and methods }

Wir haben eine kurze Beschreibung und zwei verschiedene Block-Tags - eigenständig und inline:

  • Standalone-Tags werden nach der Beschreibung mit dem Tag als erstem Wort in einer Zeile angezeigt , z. B. dem @ author- Tag
  • Inline-Tags können überall angezeigt werden und sind in geschweifte Klammern gesetzt , z. B. das @ link- Tag in der Beschreibung

In unserem Beispiel sehen wir auch zwei Arten von Block-Tags, die verwendet werden:

  • {@link} bietet einen Inline-Link zu einem Teil unseres Quellcodes, auf den verwiesen wird
  • @author der Name des Autors, der die kommentierte Klasse, Methode oder das kommentierte Feld hinzugefügt hat

2.3. Javadoc auf Feldebene

Wir können in unserer SuperHero- Klasse auch eine Beschreibung ohne solche Block-Tags verwenden :

/** * The public name of a hero that is common knowledge */ private String heroName;

In privaten Feldern wird Javadoc nicht für sie generiert, es sei denn, wir übergeben die Option -private explizit an den Befehl Javadoc.

2.4. Javadoc auf Methodenebene

Methoden können eine Vielzahl von Javadoc-Block-Tags enthalten.

Werfen wir einen Blick auf eine Methode, die wir verwenden:

/** * 

This is a simple description of the method. . . * Superman! *

* @param incomingDamage the amount of incoming damage * @return the amount of health hero has after attack * @see HERO-402 * @since 1.0 */ public int successfullyAttacked(int incomingDamage) { // do things return 0; }

Die Methode erfolgreichAttacked enthält sowohl eine Beschreibung als auch zahlreiche eigenständige Block-Tags.

Es gibt viele Block-Tags, mit denen die richtige Dokumentation erstellt werden kann, und wir können alle Arten von Informationen einschließen. Wir können sogar grundlegende HTML-Tags in den Kommentaren verwenden.

Lassen Sie uns die Tags durchgehen, auf die wir im obigen Beispiel stoßen:

  • @param bietet eine nützliche Beschreibung der Parameter oder Eingaben einer Methode, die erwartet werden sollten
  • @return beschreibt, was eine Methode zurückgeben wird oder kann
  • @see generiert einen Link ähnlich dem Tag {@link} , jedoch mehr im Kontext einer Referenz und nicht inline
  • @since gibt an, welche Version die Klasse, das Feld oder die Methode zum Projekt hinzugefügt wurde
  • @version gibt die Version der Software an, die üblicherweise mit% I% - und% G% -Makros verwendet wird
  • @throws wird verwendet, um die Fälle weiter zu erläutern, in denen die Software eine Ausnahme erwarten würde
  • @deprecated gibt eine Erklärung, warum Code veraltet war, wann er möglicherweise veraltet war und welche Alternativen es gibt

Obwohl beide Abschnitte technisch optional sind, benötigen wir mindestens einen für das Javadoc-Tool, um etwas Sinnvolles zu generieren.

3. Javadoc-Generation

Um unsere Javadoc-Seiten zu generieren, schauen wir uns das Befehlszeilentool an, das mit dem JDK und dem Maven-Plugin geliefert wird.

3.1. Javadoc-Befehlszeilenprogramm

Das Javadoc-Befehlszeilentool ist sehr leistungsfähig, mit einer gewissen Komplexität verbunden.

Wenn Sie den Befehl javadoc ohne Optionen oder Parameter ausführen, werden Fehler und Ausgabeparameter erwartet.

Wir müssen mindestens angeben, für welches Paket oder welche Klasse die Dokumentation generiert werden soll.

Öffnen Sie eine Befehlszeile und navigieren Sie zum Projektverzeichnis.

Angenommen, die Klassen befinden sich alle im Ordner src im Projektverzeichnis:

[email protected]:~$ javadoc -d doc src\*

Dadurch wird eine Dokumentation in einem Verzeichnis namens doc generiert, wie mit dem Flag - d angegeben . Wenn mehrere Pakete oder Dateien vorhanden sind, müssen wir alle bereitstellen.

Die Verwendung einer IDE mit der integrierten Funktionalität ist natürlich einfacher und wird allgemein empfohlen.

3.2. Javadoc Mit Maven Plugin

Wir können auch das Maven Javadoc Plugin verwenden:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0  1.8 1.8   ...    

Im Basisverzeichnis des Projekts führen wir den Befehl aus, um unsere Javadocs in einem Verzeichnis in target \ site zu generieren:

[email protected]:~$ mvn javadoc:javadoc

Das Maven-Plugin ist sehr leistungsfähig und ermöglicht die nahtlose Erstellung komplexer Dokumente.

Lassen Sie uns nun sehen, wie eine generierte Javadoc-Seite aussieht:

Wir können eine Baumansicht der Klassen sehen, die unsere SuperHero- Klasse erweitert. Wir können unsere Beschreibung, Felder und Methoden sehen und auf Links klicken, um weitere Informationen zu erhalten.

Eine detaillierte Ansicht unserer Methode sieht folgendermaßen aus:

3.3. Benutzerdefinierte Javadoc-Tags

Zusätzlich zur Verwendung vordefinierter Block-Tags zum Formatieren unserer Dokumentation können wir auch benutzerdefinierte Block-Tags erstellen.

In order to do so, we just need to include a -tag option to our Javadoc command line in the format of ::.

In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:

[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

In order to use this tag, we can add it to the block section of a Javadoc comment:

/** * This is an example... * @location New York * @returns blah blah */

The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.

In order to set up the same tag above for our project, we can add the following to the section of our plugin:

...   location a Notable Places:   ...

This way allows us to specify the custom tag once, instead of specifying it every time.

4. Conclusion

In diesem kurzen Einführungs-Tutorial wurde beschrieben, wie Sie grundlegende Javadocs schreiben und mit der Javadoc-Befehlszeile generieren.

Eine einfachere Möglichkeit, die Dokumentation zu erstellen, besteht darin, integrierte IDE-Optionen zu verwenden oder das Maven-Plugin in unsere Datei pom.xml aufzunehmen und die entsprechenden Befehle auszuführen.

Die Codebeispiele finden Sie wie immer auf GitHub.