Einführung in den Befehl javadoc
Kapitel 6: Javadoc generieren
Diesmal handelt es sich nicht um einen Implementierungsaspekt wie Javadoc-Spezifikationen und Schreibmethode, sondern um einen Ich möchte mich darauf konzentrieren, wie der Befehl javadoc verwendet und bedient wird. In Bezug auf das Schreiben von Kommentaren, als ich Bücher über das Schreiben von Javadoc lernte Ich möchte es zusammenfassen.
Javadoc Übersicht
Der Befehl Javadoc analysiert Deklarationen und Kommentare in Java-Quelldateien und standardmäßig öffentliche Klasse, geschützte Klasse, verschachtelte Klasse (ausgenommen anonyme innere Klasse), Implementierungsdokumentation für Schnittstellen, Konstruktoren, Methoden und Felder Im HTML-Format generieren.
Javadoc-Seitenliste
Was ist mit Javadoc, dem Produkt des Befehls javadoc, um es später einfacher zu erklären? Hier ist ein Beispiel, wie die Seite generiert wird.
Grundlegende Inhaltsseite
- ** Übersichtsseite ** (Übersichtszusammenfassung.html) Javadoc Top-Seite. Es wird eine Übersicht über die gesamte Einheit, API und den Paketsatz geschrieben.
- ** Paketseite ** (package-summary.html) Eine Seite, die für jedes Paket vorhanden ist. Der Umriss des Pakets ist geschrieben.
- ** Klassenseite / Schnittstellenseite ** (classname.html) Seiten, die für jede Klasse und Schnittstelle existieren. Enthält Informationen zu den Mitgliedern und Methoden, die zur Klasse gehören.
~ Übersichtsseite ~
~ Paketseite ~
~ Klassenseite ~
Gegenseitige Referenzseite
- ** Seite mit Klassenhierarchie ** (Übersichtsbaum.html) Für jeden Javadoc gibt es einen. Die Elemente, zu denen sie gehören, können hierarchisiert und aufgelistet werden.
- ** Seite der Klassenhierarchie ** (package-tree.html) Für jedes Paket gibt es eine. Zu einem Paket gehörende Elemente können hierarchisiert und aufgelistet werden.
- ** Spezifikationsseite ** (package-use.html) Sie können die Zielklassen, Pakete und Klassen auflisten, die die Schnittstelle verwenden.
- ** Veraltete API-Seite ** (veraltete Liste.html) Sie können veraltete Klassen, Methoden usw. auflisten, die möglicherweise in Zukunft entfernt werden.
- ** Seite mit konstanten Feldwerten ** (Konstante-Werte.html) Seite für statische Feldwerte
- ** Seite mit serialisiertem Formular ** (serialized-form.html) Eine Seite über Klassen, die serialisiert (externalisiert) werden können.
- ** Index ** (Index- *. Html) Alle Klassen, Schnittstellen, Konstruktoren, Felder und Methoden, Kann in alphabetischer Reihenfolge aufgelistet werden.
Support-Seite
--Hilfeseite (help-doc.html) Es enthält eine Navigationsleiste und Anweisungen für jede Seite.
HTML-Frame
Der Befehl javadoc erstellt einige HTML-Frames. Wenn es ein Paket gibt, wird links unten ein Rahmen für die Klasse und rechts ein Rahmen für Details erstellt. Wenn mehrere Pakete vorhanden sind, wird oben links ein Rahmen für das Paket hinzugefügt.
Format des Javadoc-Befehls
#Die Reihenfolge, in der die Argumente des Befehls javadoc angegeben werden, ist beliebig.
$ javadoc [options] [packagenames | sourcefilenames] [-subpackages pkg1:pkg2:...]
- options
Befehlszeilenoptionen, die an den Befehl javadoc übergeben werden. - packagenames
Der Name des zu verarbeitenden Pakets. Geben Sie als`java.lang java.awt``` an. Sie müssen das Zielpaket einzeln angeben und dürfen keine Platzhalter verwenden. Um es rekursiv anzugeben, verwenden Sie die unten beschriebenen`-Unterpakete```. - sourcefilenames
Der Name der zu verarbeitenden Quelldatei. Jede Datei beginnt mit einem Pfad, z. B. einem Sternchen (\ *). Sie können Platzhalter einfügen. - -subpackages pkg1:pkg2:...
Rekursiv innerhalb des angegebenen Pakets und seiner Unterpakete aus der Quelldatei Generieren Sie ein Dokument. Es ist nicht erforderlich, den Paketnamen und den Namen der Quelldatei anzugeben.
Angeben der Quelldatei
Quelldateityp
Es gibt die folgenden vier Zieldateien, die beim Generieren von Javadoc analysiert werden.
- ** Klassendatei ** Eine Datei, die auf .java endet. Wenn der Klassenname gemäß der Java-Konvention ungültig ist, wird er nicht verarbeitet. Beispiel) Beginnen Sie mit einer Zahl. "-"einschließlich. Eine solche
- ** Paketkommentardatei ** Es kann für jedes Paket platziert werden und befindet sich in derselben Hierarchie wie die Java-Datei. Beschreiben Sie die Gliederung des Pakets. Der Dateiname ist fest und es gibt die folgenden zwei Spezifikationen.
- Vor JDK1.5: package.html --JJ1.5 oder höher: package-info.java
- ** Zusammenfassende Kommentardatei ** Eine Datei zum Generieren einer Übersichtsseite. Der Dateiname und der Speicherort sind willkürlich, aber normalerweise Machen Sie es Übersicht.html und platzieren Sie es auf der obersten Ebene des Quellbaums. Wird durch Angabe des Namens der zusammenfassenden Kommentardatei mit der Option -overview generiert.
- ** Dateien im Verzeichnis doc-files ** Sie möchten beispielsweise eine Bilddatei in Javadoc einer Klasse namens Sample class einfügen. Wenn Sie Dateien verwenden möchten, die von den Regeln von .java abweichen, rufen Sie doc-files in derselben Hierarchie wie .java auf Durch Erstellen und Anordnen eines Verzeichnisses kann die gespeicherte Datei analysiert werden.
So geben Sie verschiedene Quelldateien an
Es gibt drei Möglichkeiten, die Quelldatei anzugeben.
** 1. Geben Sie das Paket an ** Da Platzhalter nicht verwendet werden können, trennen Sie sie mit einem Leerzeichen halber Breite im folgenden Format. Geben Sie alle Pakete einzeln an. Die Spezifikation muss eine vollständige Spezifikation sein.
java.lang java.lang.reflect java.awt
** 2. Geben Sie den Pfad der Quelldatei an **
Geben Sie den Pfad der Quelldatei an. Es kann entweder ein absoluter oder ein relativer Pfad angegeben werden.
Geben Sie für einen relativen Pfad den relativen Pfad aus dem aktuellen Verzeichnis an.
Platzhalter können verwendet werden. Wenn Sie mehrere angeben, trennen Sie sie durch ein Leerzeichen mit halber Breite.
#### **`/src/java/awt/Sample.java src/java/awt/*Bar.java`**
** 3. Geben Sie Pakete rekursiv mit der Option -subpackages an ** Wenn Sie ein Paket angeben, können Sie den Bereich einschließlich der Unterpakete angeben. Platzhalter können nicht verwendet werden. Trennen Sie bei der Angabe mit einem Doppelpunkt (:) im folgenden Format.
javax.swing
> Normalerweise werden einzelne Pakete selten angegeben.
Geben Sie den Pfad der Quelldatei mit einem Platzhalter oder mit der Option -subpackages an
Es wird hauptsächlich rekursiv angegeben.
** Bsp. Bei Angabe im Paket **
Wenn Sie die Quelldatei im Paket angeben,
Sie können der Pakethierarchie nicht folgen, ohne den Paketstamm anzugeben.
Daher muss das Verzeichnis angegeben werden, das der Startpunkt des Pakets ist.
Es gibt zwei Möglichkeiten, ein Verzeichnis anzugeben:
- Verschieben Sie das aktuelle Verzeichnis in das Startverzeichnis und führen Sie den Befehl javadoc aus
- Geben Sie das Startverzeichnis mit der Option -sourcepath an
## Javadoc-Optionen
Zu den Optionen, die an den Befehl javadoc übergeben werden können, gehören:
Es gibt zwei Optionen: Javadoc-Befehlsoptionen und von Doclet bereitgestellte Optionen.
Ich werde nicht auf Details über Docklets eingehen.
Stellen Sie sich das als Vorlage vor, die das Javadoc-Format bereitstellt.
Wenn Sie kein benutzerdefiniertes Doclet explizit angeben, wird das Standard-Doclet ausgewählt.
### Hauptoptionen
--- Übersicht <Pfad \ Dateiname>
Durch Angabe der Übersicht.html an einer beliebigen Stelle mit dem Pfad wird die Übersicht.html analysiert und
Platzieren Sie es auf der Übersichtsseite (Übersichtszusammenfassung.html).
Geben Sie für den Pfad den relativen Pfad aus dem durch -sourcepath angegebenen Verzeichnis an.
--- d <Pfad>
Geben Sie das generierte Javadoc unter dem angegebenen Pfad aus.
--- Quelle <Version>
Geben Sie die Version des Quellcodes an. Passen Sie die Version an die der Zusammenstellung an.
--1.5: Akzeptiert den in JDK 1.5 eingeführten Code. Standardwert.
--1.4: Akzeptiert Code einschließlich der in JDK 1.4 eingeführten Zusicherungen.
--1.3: Unterstützt keine Zusicherungen, Generika und andere Sprachfunktionen, die in JDK 1.3 und höher eingeführt wurden.
--- Klassenpfad <Pfadliste>
Geben Sie den Pfad für die Suche nach der Referenzklasse (.class) an.
Referenzklassen sind alle dokumentierten Klassen und alle, auf die diese Klassen verweisen.
Beinhaltet Klasse. Der Suchbereich ist das Unterverzeichnis unter dem angegebenen Pfad.
Wenn der Klassenpfad nicht festgelegt ist, ist das aktuelle Verzeichnis der Klassenpfad.
--- Quellpfad <Pfadliste>
Geben Sie den Klassenpfad der Quelldatei an. (Wenn Sie Pakete oder Unterpakete übergeben)
Der Suchbereich ist das Unterverzeichnis unter dem angegebenen Pfad. Mit dieser Option
Wenn -sourcepath weggelassen wird, wird ** der gleiche Wert wie der Klassenpfad ** festgelegt.
Wenn -classpath ebenfalls weggelassen wird, wird ** aktuelles Verzeichnis ** gesetzt.
--- J <Java-Befehlsoptionen>
Übergeben Sie Optionen an das Laufzeitsystem Java, auf dem Javadoc ausgeführt wird. (-J-Xmx32m usw.)
### Angegebene Optionen, die dokumentiert werden sollen
--- Unterpakete <Paket 1: Paket 2 ...>
Der Generierungsbereich kann das angegebene Paket und seine Unterpakete und darunter sein. (Es können mehrere Pakete angegeben werden)
-sourcepath ist erforderlich, wenn -subpackages verwendet werden.
--- Bootclasspath <Pfadliste>
Geben Sie den Pfad an, in dem sich die Startklasse befindet.
### Zu dokumentierende Steuerungssystemoptionen
- -public
Nur öffentliche Klassen und Mitglieder anzeigen.
- -protected
Nur geschützte und öffentliche Klassen und Mitglieder anzeigen. Standardeinstellungen.
- -package
Nur Paket-, geschützte und öffentliche Klassen und Mitglieder anzeigen.
- -private
Alle Klassen und Mitglieder anzeigen.
--- <Paket 1: Paket 2 ...> ausschließen
Schließt das angegebene Paket und seine Unterpakete von der durch -subpackages angegebenen Liste aus.
### Docklet-Optionen
--- doclet <Klasse>
Geben Sie ein anderes Docklet als das Standard-Docklet an. Geben Sie die Startklasse mit vollständiger Spezifikation an.
Das Format zum Angeben der Startklasse lautet `` `-doclet com.example.doclets.SampleDoclet```.
Der Klassenpfad zur Startklasse wird durch die Option -docletpath definiert.
--- docletpath <Klassenpfad 1: Klassenpfad 2 ...>
Die Doclet-Startklassendatei, die durch die Option -doclet und die abhängige JAR-Datei angegeben wird
Geben Sie den Pfad zu an. Der Pfad der JAR-Datei, wenn sich die Startklassendatei in der JAR-Datei befindet
Nur kann angegeben werden. Sie können einen absoluten oder einen relativen Pfad aus dem aktuellen Verzeichnis angeben.
Diese Option wird nicht benötigt, wenn sich die gewünschte Doclet-Startklasse im Suchpfad befindet.
```shell
#SampleDocklet/src/com/example/Angenommen, es befindet sich direkt unter den Dokumenten
-doclet com.example.doclets.SampleDoclet -docletpath /src:/lib/doclet.jar
Debug-Optionen
- -verbose
Zeigen Sie detaillierte Nachrichten an, während Sie javadoc ausführen. Wenn nicht angegeben, beim Laden der Quelldatei und beim Generieren des Dokuments (pro Quelldatei), Zum Zeitpunkt der Sortierung wird eine Meldung angezeigt (nur einmal in einer Ausführung). Falls angegeben, detaillierte Informationen wie die Zeit (in Millisekunden), die zum Analysieren jeder Java-Quelldatei erforderlich ist Eine Meldung wird angezeigt. - -quiet
Unterdrücken Sie andere Meldungen als Fehlermeldungen und Warnmeldungen.
Internationalisierungsoptionen
--- Gebietsschema
Lauf
Hier werden Kommentare und Dateien für die Javadoc-Generierung zum bisher verwendeten Beispielcode hinzugefügt.
Die folgende hinzugefügte Konfiguration wird als Beispielcode verwendet.
UseCommons.java
package com.example.app;
import org.apache.commons.lang3.StringUtils;
import com.example.util.StrFactory;
/**
*Eine Klasse zur Verwendung von Apache Commons.
*/
public class UseCommons {
public static void main(String[] args) {
System.out.println(CommonsHelper.returnNgStrIfHasProbrem(null));
System.out.println(CommonsHelper.returnNgStrIfHasProbrem(""));
StrFactory strFactory = new StrFactory();
System.out.println(CommonsHelper.returnNgStrIfHasProbrem(strFactory.sayHelloWorld()));
}
static class CommonsHelper {
static String returnNgStrIfHasProbrem (String target) {
if (StringUtils.isEmpty(target)) {
return "NG";
} else if (StringUtils.isBlank(target)) {
return "NG";
}
return target;
}
}
}
StrFactory.java
package com.example.util;
/**
*Eine Factory-Klasse zum Generieren verschiedener Zeichenfolgen.
*/
public class StrFactory {
/**
* "Hello World!"Wird zurückgegeben.
*/
public String sayHelloWorld() {
return "Hello World!";
}
}
package.html
<html>
<body>
Dies ist ein Beispiel für einen Paketkommentar.
</body>
</html>
overview.html
<html>
<body>
Dies ist ein zusammenfassender Kommentar des Beispiels.
</body>
</html>
Führen Sie nach dem Vorbereiten der Quelldatei den folgenden Befehl aus, wie oben erwähnt.
#Das aktuelle Verzeichnis ist/java-Es ist eine Probe.
$ javadoc -classpath ./src:./lib/commons-lang3-3.10.jar -subpackages com.example -overview ./overview.html -d ./docs
Bei der Ausführung wird Javadoc in / java-sample / docs generiert, das als Ausgabeziel angegeben ist.
Öffnen Sie die Datei index.html, um Javadoc anzuzeigen.
Unten ist die tatsächliche Ausgabe.
abschließend
Der Beispielcode enthält nicht die minimal erforderlichen Kommentare. Verwenden Sie HTML für Kommentare, fügen Sie Bilder ein, verweisen Sie auf externe Bibliotheken usw. Sie können verschiedene Dinge tun, also lesen oder recherchieren Sie Fachbücher über deren Implementierung. Ich hoffe du wirst lernen.
Recommended Posts