Einführung in Javadoc

1. Überblick

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 der API-Dokumentation aus den im Quellcode vorhandenen Kommentaren.

Voraussetzungen:

  1. JDK 1.4 (JDK 7 wird für die neueste Version des Maven empfohlen.)

Javadoc-Plugin) . Der JDK-Ordner /bin wurde der Umgebungsvariable PATH hinzugefügt

  1. (Optional) eine IDE mit integrierten Tools

Beginnen wir mit Kommentaren.

  • Javadoc-Kommentarstruktur sieht einem regulären mehrzeiligen Kommentar sehr ähnlich ** , aber der Hauptunterschied ist der zusätzliche Stern 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 allen Klassen, Methoden oder Feldern platziert werden, die wir dokumentieren möchten. **

Diese Kommentare bestehen im Allgemeinen aus zwei Abschnitten:

  1. Die Beschreibung dessen, was wir kommentieren

  2. Die eigenständigen Block-Tags (mit dem Symbol " @ " gekennzeichnet), die

Beschreiben bestimmter Metadaten

In unserem Beispiel werden wir einige der gebräuchlichsten Block-Tags verwenden. Eine vollständige Liste der Block-Tags finden Sie im https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html (Referenzhandbuch).

2.2. Javadoc auf Klassenstufe

Schauen wir uns an, 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 - Standalone und Inline:

  • Standalone-Tags werden nach der Beschreibung mit dem Tag als erstes angezeigt

Wort in einer Zeile, z. B. das @ author -Tag Inline-Tags können überall auftauchen und sind mit geschweiften Umrandungen versehen

Klammern ** , z. B. das @ link -Tag in der Beschreibung

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

  • \ {@ link} enthält einen Inline-Link zu einem referenzierten Teil unserer Quelle

Code ** @ author der Name des Autors, der die Klasse, Methode oder das Feld hinzugefügt hat

das ist kommentiert

2.3. Javadoc at Field Level

In unserer Klasse SuperHero können wir auch eine Beschreibung ohne Block-Tags verwenden:

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

Für private Felder wird kein Javadoc generiert, es sei denn, wir übergeben die Option -private explizit an den Javadoc-Befehl.

2.4. Javadoc auf Methodenebene

Methoden können verschiedene Javadoc-Block-Tags enthalten.

Schauen wir uns eine Methode an, die wir verwenden:

----/** **
 **  <p>This is a simple description of the method. . .
 **  <a href="http://www.supermanisthegreatest.com">Superman!</a>
 **  </p>
 **  @param incomingDamage the amount of incoming damage
 **  @return the amount of health hero has after attack
 **  @see <a href="http://www.link__to__jira/HERO-402">HERO-402</a>
 **  @since 1.0
 ** /public int successfullyAttacked(int incomingDamage) {
   //do things
    return 0;
}
----

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

Es gibt viele Block-Tags, mit deren Hilfe Sie die richtige Dokumentation erstellen können, und wir können alle Arten von Informationen einbinden. Wir können sogar grundlegende HTML-Tags in den Kommentaren verwenden.

Gehen wir die Tags aus, die uns im obigen Beispiel begegnen:

  • @ param enthält eine nützliche Beschreibung der Parameter einer Methode oder

Eingabe sollte es erwarten ** @ return beschreibt, was eine Methode zurückgeben wird oder kann

  • @ see erzeugt einen Link, der dem Tag \ {@ link} ähnelt, aber mehr in

den Kontext einer Referenz und nicht inline ** @ since gibt an, welche Version der Klasse, des Feldes oder der Methode hinzugefügt wurde

zum Projekt ** @ version gibt die Version der Software an, die üblicherweise mit verwendet wird

% I% und% G% Makros ** @ throws wird verwendet, um die Fälle näher zu erläutern, die die Software ausführen würde

eine Ausnahme erwarten ** @ deprecated gibt an, warum der Code wann abgelehnt wurde

möglicherweise veraltet und welche Alternativen es gibt

Obwohl beide Abschnitte technisch optional sind, benötigen wir mindestens einen, damit das Javadoc-Tool etwas Sinnvolles generiert.

3. Javadoc Generation

Um unsere Javadoc-Seiten zu erstellen, möchten wir uns das Befehlszeilentool, das mit dem JDK geliefert wird, sowie das Maven-Plugin ansehen.

3.1. Javadoc-Befehlszeilentool

Das Javadoc-Befehlszeilentool ist sehr leistungsfähig, hat jedoch eine gewisse Komplexität.

Wenn Sie den Befehl javadoc ohne Optionen oder Parameter ausführen, führt dies zu einem Fehler und zu erwartenden Ausgabeparametern.

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

Öffnen wir 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 Dokumentation in einem Verzeichnis mit dem Namen doc generiert, das mit dem Flag – d angegeben ist. Wenn mehrere Pakete oder Dateien vorhanden sind, müssen wir alle angeben.

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

3.2. Javadoc mit Maven-Plugin

Wir können auch das Maven Javadoc-Plugin verwenden:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
            <tags>
            ...
            </tags>
        </plugin>
    </plugins>
</build>

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
----

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

/uploads/overview-125x125.png%20125w

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

Eine detaillierte Ansicht unserer Methode sieht folgendermaßen aus:

3.3. Benutzerdefinierte Javadoc-Tags

Neben der Verwendung vordefinierter Block-Tags zum Formatieren unserer Dokumentation können wir auch benutzerdefinierte Block-Tags erstellen.

Dazu müssen Sie unserer Javadoc-Befehlszeile lediglich die Option -tag im Format <Tag-Name>: <Speicherorte erlaubt>: <Header> hinzufügen.

Um ein benutzerdefiniertes Tag mit dem Namen @ location , das überall erlaubt ist, zu erstellen, das in unserem generierten Dokument in der Kopfzeile "Notable Locations" angezeigt wird, müssen wir Folgendes ausführen:

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

Um dieses Tag zu verwenden, können wir es dem Blockabschnitt eines Javadoc-Kommentars hinzufügen:

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

Das Maven Javadoc-Plugin ist flexibel genug, um auch Definitionen unserer benutzerdefinierten Tags in unserer pom.xml zuzulassen.

Um dasselbe Tag oben für unser Projekt einzurichten, können wir dem Abschnitt <<tags> __ unseres Plugins Folgendes hinzufügen:

...
<tags>
    <tag>
        <name>location</name>
        <placement>a</placement>
        <head>Notable Places:</head>
    </tag>
</tags>
...

Auf diese Weise können wir das benutzerdefinierte Tag einmal angeben, anstatt es jedes Mal anzugeben.

4. Fazit

In dieser Kurzanleitung zur Einführung wurde beschrieben, wie Sie grundlegende Javadocs schreiben und mit der Javadoc-Befehlszeile generieren.

Eine einfachere Methode zum Erstellen der Dokumentation besteht darin, alle integrierten 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 unter https://github.com/eugenp/tutorials/tree/master/core-java