what is javadoc how use it generate documentation
In diesem Tutorial werden die JavaDoc-Tools und JavaDoc-Kommentare sowie Methoden zum Generieren der Codedokumentation erläutert:
JavaDoc ist ein spezielles Tool, das im JDK enthalten ist. Es wird verwendet, um die Codedokumentation von Java-Quellcode im HTML-Format zu generieren.
Es ist ein Dokumentationsgenerator für die Java-Sprache von Sun Microsystems (derzeit Oracle Corporation).
=> Überprüfen Sie ALLE Java-Tutorials hier.
Was du lernen wirst:
Was ist JavaDoc?
Dieses Tool verwendet das Format 'Dokumentkommentare', um Java-Klassen zu dokumentieren. IDEs wie Eclipse, IntelliJIDEA oder NetBeans verfügen über ein integriertes JavaDoc-Tool zum Generieren von HTML-Dokumentation. Wir haben auch viele Datei-Editoren auf dem Markt, die dem Programmierer helfen können, JavaDoc-Quellen zu erstellen.
Neben der Quellcodedokumentation bietet dieses Tool auch eine API, die 'Doclets' und 'Taglets' erstellt, mit denen wir die Struktur einer Java-Anwendung analysieren.
Zu beachten ist, dass dieses Tool die Leistung der Anwendung in keiner Weise beeinträchtigt, da der Compiler alle Kommentare während der Kompilierung des Java-Programms entfernt.
Das Schreiben von Kommentaren in das Programm und das anschließende Generieren der Dokumentation mit JavaDoc soll dem Programmierer / Benutzer helfen, den Code zu verstehen.
Die von JavaDoc generierte HTML-Dokumentation ist eine API-Dokumentation. Es analysiert die Deklarationen und generiert eine Reihe von Quelldateien. Die Quelldatei beschreibt Felder, Methoden, Konstruktoren und Klassen.
Beachten Sie, dass wir spezielle JavaDoc-Kommentare in das Programm aufnehmen müssen, bevor wir das JavaDoc-Tool für unseren Quellcode verwenden.
Fahren wir nun mit den Kommentaren fort.
JavaDoc-Kommentare
Die Java-Sprache unterstützt die folgenden Arten von Kommentaren.
# 1) Einzeilige Kommentare: Der einzeilige Kommentar wird mit „ // // ”Und wenn der Compiler auf diese stößt, ignoriert er alles, was diesen Kommentaren folgt, bis zum Ende der Zeile.
# 2) Mehrzeilige Kommentare: Mehrzeilige Kommentare werden mit „ /*….*/ ”. Bei der Begegnung mit der Sequenz '/ *' ignoriert der Compiler alles, was dieser Sequenz folgt, bis er auf die Schlusssequenz '* /' stößt.
# 3) Dokumentationskommentare: Diese werden als Doc-Kommentare bezeichnet und vom Tool zum Generieren der API-Dokumentation verwendet. Die Dokumentkommentare sind mit „ / ** Dokumentation * / ”. Wie wir sehen können, unterscheiden sich diese Kommentare von den oben beschriebenen normalen Kommentaren. Die Dokumentkommentare können auch HTML-Tags enthalten, wie wir in Kürze sehen werden.
Um mit diesem Tool API-Dokumentation zu generieren, müssen wir diese Dokumentationskommentare (Dokumentkommentare) in unserem Programm bereitstellen.
wie man eine Stoßwellen-Flash-Datei abspielt
Struktur eines JavaDoc-Kommentars
Die Struktur des Dokumentkommentars in Java ähnelt dem mehrzeiligen Kommentar, außer dass der Dokumentkommentar im Eröffnungs-Tag ein zusätzliches Sternchen (*) enthält. Der Dokumentkommentar beginnt also mit '/ **' anstelle von '/ *'.
Darüber hinaus können Kommentare im JavaDoc-Stil auch HTML-Tags enthalten.
JavaDoc-Kommentarformat
Basierend auf dem Programmierkonstrukt, für das wir dokumentieren möchten, können wir Dokumentkommentare über jedem Konstrukt wie Klasse, Methode, Feld usw. platzieren. Lassen Sie uns Beispiele für die Dokumentkommentare der einzelnen Konstrukte durchgehen.
Format auf Klassenebene
Das Dokumentkommentarformat auf Klassenebene sieht wie folgt aus:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } Wie oben gezeigt, enthält ein Dokumentkommentar auf Klassenebene alle Details, einschließlich des Autors der Klasse, gegebenenfalls Links usw.
Format auf Methodenebene
Im Folgenden finden Sie ein Beispiel für ein Dokumentformat auf Methodenebene.
/** * simple method description … * JavaDoc! *
* @param msg the message to be printed * @return void * @see JavaDoc * @since 2.0 */ public void printMessage (String msg) { // do things return 0; } Wie wir aus dem obigen Beispiel sehen können, können wir im Dokumentkommentar der Methode eine beliebige Anzahl von Tags haben. Wir können auch Absätze in der Kommentarbeschreibung von haben
...
.Wir haben auch spezielle Tags, um den Rückgabewert (@return) und die Parameter der Methode (@param) zu beschreiben.
Feldebenenformat
Das folgende Beispiel zeigt den Dokumentkommentar für ein Feld.
/** * The public name of a message */ private String msg_txt;Wie aus dem obigen Beispiel hervorgeht, können wir auch einfache Kommentare ohne Tags haben. Beachten Sie, dass JavaDoc keine Dokumentation für private Felder generiert, es sei denn, wir geben mit dem Befehl JavaDoc eine private Option an.
Lassen Sie uns nun die Tags diskutieren, die mit den Dokumentkommentaren verwendet werden.
JavaDoc-Tags
Java bietet verschiedene Tags, die wir in den Dokumentkommentar aufnehmen können. Wenn wir diese Tags verwenden, analysiert das Tool diese Tags, um aus dem Quellcode eine gut formatierte API zu generieren.
Jedes Tag unterscheidet zwischen Groß- und Kleinschreibung und beginnt mit einem @ -Zeichen. Jedes Tag beginnt am Anfang der Zeile, wie aus den obigen Beispielen hervorgeht. Andernfalls behandelt der Compiler es als normalen Text. In der Regel werden dieselben Tags zusammengesetzt.
Es gibt zwei Arten von Tags, die wir in Dokumentkommentaren verwenden können.
# 1) Tags blockieren : Block-Tags haben die Form von @Verlinke den Namen .
Block-Tags können im Tag-Bereich platziert werden und folgen der Hauptbeschreibung .
# 2) Inline-Tags ::Inline-Tags sind in geschweiften Klammern eingeschlossen und haben die Form: {@Verlinke den Namen} . Die Inline-Tags können an einer beliebigen Stelle im Dokumentkommentar platziert werden.
In der folgenden Tabelle sind alle Tags aufgeführt, die in den Dokumentkommentaren verwendet werden können.
| Etikett | Beschreibung | Gilt für |
|---|---|---|
| @ Rückgabe Beschreibung | Bietet eine Beschreibung des Rückgabewerts. | Methode |
| @author xyz | Gibt den Autor der Klasse, Schnittstelle oder Aufzählung an. | Klasse, Schnittstelle, Aufzählung |
| {@docRoot} | Dieses Tag hat den relativen Pfad zum Stammverzeichnis des Dokuments. | Klasse, Schnittstelle, Aufzählung, Feld, Methode |
| @ Version Version | Gibt den Softwareversionseintrag an. | Klasse, Schnittstelle, Aufzählung |
| @ seit dem Text | Gibt an, wann diese Funktionalität vorhanden ist | Klasse, Schnittstelle, Aufzählung, Feld, Methode |
| @ Siehe Referenz | Gibt Verweise (Links) auf andere Dokumentationen an | Klasse, Schnittstelle, Aufzählung, Feld, Methode |
| @param Name Beschreibung | Wird verwendet, um den Methodenparameter / das Argument zu beschreiben. | Methode |
| @exception Klassenname Beschreibung | Gibt eine Ausnahme an, die die Methode in ihren Code einfügen kann. | Methode |
| @throws Klassenname Beschreibung | ||
| @ veraltete Beschreibung | Gibt an, ob die Methode veraltet ist | Klasse, Schnittstelle, Aufzählung, Feld, Methode |
| {@inheritDoc} | Wird verwendet, um die Beschreibung im Falle einer Vererbung von der überschriebenen Methode zu kopieren | Überschreibende Methode |
| {@link reference} | Bietet Verweise oder Links zu anderen Symbolen. | Klasse, Schnittstelle, Aufzählung, Feld, Methode |
| {@linkplain Referenz} | Wie {@link}, wird jedoch im Klartext angezeigt. | Klasse, Schnittstelle, Aufzählung, Feld, Methode |
| {@value #STATIC_FIELD} | Beschreiben Sie den Wert eines statischen Feldes. | Statisches Feld |
| {@code literal} | Wird verwendet, um den Literaltext in einer Code-Schriftart zu formatieren, die {@literal} ähnelt.. | Class, Interface, Enum, Field, Method |
| {@literal literal} | Indicates literal text. the enclosed text is interpreted literally without any style formatting. | Class, Interface, Enum, Field, Method |
| {@serial literal} | Description of a serializable field. | Field |
| {@serialData literal} | Documents the data written by the writeExternal( ) or writeObject( ) methods. | Field, Method |
| {@serialField literal} | Describes an ObjectStreamField component. | Field |
Generate Java Doc
To create a JavaDoc you do not need to compile the Java file. We can generate JavaDoc documentation in two ways.
#1) Using JavaDoc Command Via Command Line
The command-line tool allows us to run the command through it.
This command can be executed on a command line and has the following syntax.
user@sth:~$javadoc –d doc src*
In the above command, we assume that all the files and Java classes are in the src folder. Also, the documentation will be generated in the specified ‘doc’ directory.
Note that running the “javadoc” command without any parameters or flags results in an error.
#2) Using The Tool From Any Of The Java IDEs.
All the major Java IDEs provide built-in functionality of generating documentation using the JavaDoc tool.
Standard-Gateway ist nicht verfügbar
Using this built-in functionality is easier and also recommended than using a command-line tool to generate Java documentation.
Using JavaDoc With IntelliJIdea
Let’s generate documentation for a simple program using IntelliJIdea IDE.
We will consider the following program for which we have provided doc comments.
/** * Main class * * Please see the {@link www.softwaretestinghelp.com} class for true identity * @author SoftwareTestingHelp * */ public class Main{ /** * main method description … * JavaDoc! *
* @param args[] string array * @return void * @see JavaDoc * */ public static void main(String args[]) { System.out.println('Hello,World!!'); } } Wir wissen, dass wir das Programm oder Projekt nicht kompilieren müssen, um JavaDoc zu generieren. IntelliJIdea Ide bietet ein integriertes Tool zum Generieren der Dokumentation. Führen Sie die folgenden Schritte aus, um die Dokumentation mit IntelliJIdea zu erstellen.
- Klicken Sie auf Extras -> JavaDoc generieren
- Der folgende Bildschirm wird geöffnet, wenn auf das JavaDoc-Tool geklickt wird.
Hier können wir angeben, ob wir Dokumentation für das gesamte Projekt oder nur für eine Klasse usw. generieren möchten. Wir können auch das Ausgabeverzeichnis angeben, in dem die Dokumentationsdateien generiert werden. Es gibt verschiedene andere Spezifikationen, wie in der obigen Abbildung gezeigt.
Klicken Sie auf OK, sobald alle Parameter angegeben wurden.
- Jetzt können wir den Java Doc-Generierungsprozess im Ausgabefenster sehen. Ein Beispiel für ein Java Doc-Ausgabefenster sieht wie folgt aus:
- Nach Abschluss der Generierung werden die folgenden Dateien generiert.
- Wie wir die Main-Klasse angegeben haben, wird die Datei Main.html generiert. Beachten Sie, dass die index.html auch den gleichen Inhalt wie die Main.html hat.
- Die Datei help-doc.html enthält allgemeine Definitionen von Java-Entitäten. Ein Beispiel für den Inhalt dieser Datei ist unten dargestellt.
- In ähnlicher Weise ist unten ein Beispielinhalt in der Datei Main.html angegeben
Auf diese Weise können wir mit diesem Tool in IntelliJ idea Dokumentation erstellen. Wir können ähnliche Schritte in anderen Java-IDEs wie Eclipse und / oder NetBeans ausführen.
Häufig gestellte Fragen
F # 1) Was ist die Verwendung von JavaDoc?
Antworten: Das JavaDoc-Tool wird mit JDK geliefert. Es wird verwendet, um die Codedokumentation für Java-Quellcode im HTML-Format zu generieren. Für dieses Tool müssen die Kommentare im Quellcode in einem vordefinierten Format wie /**….*/ bereitgestellt werden. Diese werden auch als Dokumentkommentare bezeichnet.
F # 2) Was ist das Java-Dokumentationsbeispiel?
Antworten: Das Java Doc-Dokumentationstool generiert HTML-Dateien, damit wir die Dokumentation über den Webbrowser anzeigen können. Das echte Live-Beispiel für JavaDoc-Dokumentation ist die Dokumentation für Java-Bibliotheken bei Oracle Corporation, http://download.oracle.com/javase/6/. docs /Feuer/.
F # 3) Benötigen private Methoden JavaDoc?
Antworten: Nein. Private Felder und Methoden sind nur für Entwickler. Es ist nicht logisch, Dokumentation für private Methoden oder Felder bereitzustellen, auf die der Endbenutzer nicht zugreifen kann. Java Doc generiert auch keine Dokumentation für private Entitäten.
F # 4) Was ist der JavaDoc-Befehl?
qa Fragen und Antworten zu Vorstellungsgesprächen
Antworten: Dieser Befehl analysiert die Deklarationen und Dokumentkommentare in Java-Quelldateien und generiert entsprechende HTML-Dokumentationsseiten mit Dokumentation für öffentliche und geschützte Klassen, verschachtelte Klassen, Konstruktoren, Methoden, Felder und Schnittstellen.
JavaDoc generiert jedoch keine Dokumentation für private Entitäten und anonyme innere Klassen.
Fazit
In diesem Lernprogramm wurde das mit JDK gelieferte JavaDoc-Tool beschrieben, das zum Generieren der Codedokumentation für Java-Quellcode im HTML-Format hilfreich ist. Wir können Dokumentation generieren, indem wir entweder den Java Doc-Befehl über das Befehlstool ausführen oder die integrierte JavaDoc-Funktionalität verwenden, die in den meisten Java-IDEs verfügbar ist.
Wir haben gesehen, wie wir das Tool mit IntelliJIdea Java IDE verwenden können, um Dokumentation zu generieren. In diesem Lernprogramm wurden auch verschiedene Tags erläutert, die mit Dokumentkommentaren verwendet werden können, damit das Tool eine benutzerfreundliche Dokumentation mit allen Informationen zum Quellcode erstellen kann.
=> Besuchen Sie hier, um Java von Grund auf neu zu lernen.
Literatur-Empfehlungen
- Java-Grundlagen: Java-Syntax, Java-Klasse und Java-Kernkonzepte
- Java-Bereitstellung: Erstellung und Ausführung einer Java-JAR-Datei
- Java Virtual Machine: Wie JVM beim Ausführen von Java-Anwendungen hilft
- JAVA-Tutorial für Anfänger: Über 100 praktische Java-Video-Tutorials
- Java Integer und Java BigInteger Klasse mit Beispielen
- Java-Komponenten: Java Platform, JDK, JRE und Java Virtual Machine
- Wie erstelle ich eine API-Dokumentation in Postman?