Dokumentieren Sie Ihren Java-Code automatisch mit Javadoc

Wenn Sie irgendeine Art von Programmierung durchführen, werden Sie sich bewusst sein, dass eine der mühsamsten Aufgaben darin besteht, Ihren Code zu dokumentieren. Ob Sie es leicht lästig finden oder ein Unternehmen, dem Sie mit absoluter Angst begegnen, die Codedokumentation ist unerlässlich. Andere müssen verstehen, wie Ihr Code funktioniert, und Sie könnten sogar einer von ihnen sein, wenn Sie ihn zu einem späteren Zeitpunkt lesen!

Java bietet praktischerweise eine eingebaute Lösung für das Problem: Javadoc.

Javadoc kann Ihnen helfen, Ihren Code automatisch zu dokumentieren

Hoffentlich folgst du schon Gute Codierungspraktiken und fügen Sie erklärende Kommentare in Ihren Code ein. Während diese Art von In-Code-Kommentaren sicherlich hilfreich ist, bietet sie nicht wirklich etwas Vergleichbares mit einem Handbuch.

Sicher, ein anderer Programmierer kann Ihren Code durchsehen und sich über die spezifischen Klassen, Methoden und Funktionen informieren, die vor ihm liegen. Es ist jedoch äußerst schwierig, sich einen guten Überblick über den gesamten Code zu verschaffen oder Funktionen zu finden, die nützlich sein könnten, wenn Sie nicht wissen, dass sie existieren. Javadoc zielt darauf ab, dieses Problem zu lösen.

Javadoc generiert automatisch ein detailliertes und leserfreundliches HTML-Handbuch für Ihren gesamten Code. Das Beste daran ist, dass es Codekommentare verwendet, die Sie wahrscheinlich bereits schreiben.

Was genau ist Javadoc und wie funktioniert es?

Javadoc ist ein eigenständiges Programm, das mit den Versionen des Java Development Kit (JDK) von Oracle gebündelt geliefert wird. Tatsächlich können Sie es nicht separat herunterladen. Beim Herunterladen und Installieren Sie eine der JDK-Versionen von Oracle, wird auch Javadoc installiert.

Wenn Sie es ausführen, generiert Javadoc HTML-Dokumentation aus speziell formatierten Kommentaren in Ihrem Java-Quellcode. Dieser Prozess erstellt eine nützlichere, lesbarere Dokumentation und fördert gleichzeitig Best Practices.

Kurz gesagt, Javadoc ermöglicht es Ihnen, Ihren Code und seine Dokumentation gleichzeitig zu schreiben. Es vereinfacht Ihren Arbeitsablauf und ermöglicht es Ihnen, Ihre Zeit effizienter zu nutzen.

Javadoc analysiert speziell formatierte Kommentare in Ihrem Code und konvertiert sie in eine HTML-Ausgabe. Die einzige Änderung, die Sie wirklich vornehmen müssen, besteht darin, bestimmte Zeichenfolgen in Ihre Kommentare aufzunehmen. Diese teilen Javadoc mit, was Sie in die endgültige Dokumentation aufnehmen möchten.

Javadoc-Kommentare sollten einer Klassen-, Feld-, Konstruktor- oder Methodendeklaration unmittelbar vorangestellt werden. Der Kommentar selbst sollte:

• Beginnen Sie mit den drei Zeichen /**.
• Fügen Sie am Anfang jeder neuen Zeile ein Sternchen ein.
• Schließen Sie mit den beiden Zeichen */.

Innerhalb der Kommentare können Sie HTML in die endgültige Ausgabe einfügen und Tags einfügen, die Links zu relevanten Teilen Ihrer Codebasis generieren. Sie können sogar Dinge wie HTML-Bild-Tags verwenden, um Bilder in die endgültige Dokumentation einzufügen. Sobald Sie sich an das Format und die verfügbaren Tags gewöhnt haben, ist das Schreiben solcher Kommentare ein Kinderspiel.

Hier ist ein Beispiel zur Veranschaulichung einfacher Javadoc-Kommentare, die eine Funktion beschreiben, die ein Bild von einer URL erhält und auf dem Bildschirm ausgibt. Der Kommentar steht unmittelbar vor der Funktion und beschreibt, was sie tut. Dieser Kommentarblock verwendet auch drei abschnittsspezifische Tags: @param, @Rückkehr, und @sehen.

/**
* Gibt ein Image-Objekt zurück, das dann auf den Bildschirm gezeichnet werden kann.
* Das URL-Argument muss einen absoluten Wert angeben {@Verknüpfung URL}. Der Name
* Argument ist ein Bezeichner, der relativ zum URL-Argument ist.
* 

* Diese Methode kehrt immer sofort zurück, unabhängig davon, ob die
* Bild existiert. Wann Dies Applet versucht, das Bild zu zeichnen
* Bildschirm, die Daten werden geladen. Die grafischen Primitive
* Das Zeichnen des Bildes wird inkrementell auf dem Bildschirm gemalt.
*
* @param url eine absolute URL, die den Basisspeicherort des Bildes angibt
* @param Benennen Sie den Speicherort des Bildes relativ zum URL-Argument
* @Rückkehr das Bild unter der angegebenen URL
* @sehen Bild
*/
Öffentlichkeit Bild getImage(URL-URL, Zeichenfolgenname){
Versuchen {
Rückkehr getImage(Neu URL(URL, Name));
 } Fang (MalformedURLException e) {
RückkehrNull;
 }
}

Wenn Javadoc den obigen Code verarbeitet, generiert es eine Webseite ähnlich der folgenden:

Ein Browser rendert die Javadoc-Ausgabe auf die gleiche Weise wie jedes andere HTML-Dokument. Javadoc ignoriert zusätzliche Leerzeichen und Zeilenumbrüche, es sei denn, Sie verwenden HTML-Tags, um diese Leerzeichen zu erstellen.

Die am Ende des Kommentars verwendeten @tags erzeugen die Parameter, Kehrt zurück, und Siehe auch Abschnitte, die Sie sehen.

Sie sollten dem folgen @param -Tag mit dem Namen des Parameters, einem Leerzeichen und einer Beschreibung. Im obigen Fall gibt es zwei Parameter: URL und Name. Beachten Sie, dass beide unter der gleichen Parameterüberschrift in der Dokumentationsausgabe erscheinen. Sie können so viele Parameter auflisten, wie für die beschriebene Funktion oder Methode erforderlich sind.

Das @Rückkehr tag dokumentiert den Wert, den die Funktion zurückgibt, falls überhaupt. Je nach den Umständen kann es sich um eine einfache Beschreibung mit einem Wort oder um viele Sätze handeln.

Das @sehen Tag ermöglicht es Ihnen, andere Funktionen zu markieren, die verwandt oder relevant sind. In diesem Fall bezieht sich das @see-Tag auf eine andere Funktion namens einfach Bild. Beachten Sie, dass mit diesem Tag erstellte Verweise anklickbare Links sind, die es einem Leser ermöglichen, zu dem referenzierten Element im endgültigen HTML zu springen.

Es sind weitere Tags verfügbar, wie z. B. @version, @author, @exception und andere. Bei richtiger Verwendung helfen Tags dabei, Elemente miteinander in Beziehung zu setzen, und ermöglichen eine einfache Navigation durch die Dokumentation.

Ausführen von Javadoc auf Ihrem Quellcode

Sie rufen Javadoc in der Befehlszeile auf. Sie können es auf einzelne Dateien, ganze Verzeichnisse, Java-Pakete oder auf eine Liste einzelner Dateien ausführen. Standardmäßig generiert Javadoc die HTML-Dokumentationsdateien in dem Verzeichnis, in dem Sie den Befehl eingeben. Um Hilfe zu den spezifischen verfügbaren Befehlen zu erhalten, geben Sie einfach Folgendes ein:

javadoc --Hilfe

Um genau zu sehen, was Javadoc im Detail kann, sehen Sie sich die offizielle Dokumentation von an Orakel. Um einen schnellen Dokumentationssatz für eine einzelne Datei oder ein einzelnes Verzeichnis zu erstellen, können Sie eingeben javadoc in der Befehlszeile, gefolgt von einem Dateinamen oder Platzhalter.

javadoc ~/code/Dateiname.java
javadoc ~/code/*.Java

Oben ist eine Liste der Dateien und Verzeichnisse, die Javadoc erstellt hat. Wie Sie sehen können, gibt es einige davon. Aus diesem Grund sollten Sie darauf achten, dass Sie sich beim Ausführen des Programms nicht im selben Verzeichnis wie Ihr Quellcode befinden. Dadurch könnte ein ziemliches Durcheinander entstehen.

Um Ihre neu erstellten Dokumente anzuzeigen, öffnen Sie einfach die index.html Datei in Ihrem bevorzugten Browser. Sie erhalten eine Seite wie die folgende:

Dies ist die Dokumentation für eine einzelne, kurze Java-Klasse, um die Ausgabe zu demonstrieren. Die Kopfzeile zeigt den Namen der Klasse sowie die darin enthaltenen Methoden. Wenn Sie nach unten scrollen, werden detailliertere Definitionen der einzelnen Klassenmethoden angezeigt.

Wie Sie sehen können, ist diese Art der Dokumentation für jede Art von Java-Projekt, insbesondere für große Projekte mit vielen Tausend Codezeilen, von unschätzbarem Wert. Es wäre eine Herausforderung, etwas über eine große Codebasis zu lernen, indem man ihren Quellcode durchliest. Javadoc-Seiten machen diesen Prozess viel schneller und einfacher zu verfolgen.

Javadoc kann Ihnen dabei helfen, Ihren Java-Code und alle relevanten Dokumentationen übersichtlich und benutzerfreundlich zu halten. Egal, ob Sie es für Ihr vergessliches Zukunfts-Ich tun oder um einem großen Team die Arbeit zu erleichtern, Javadoc ist ein leistungsstarkes Tool, das die Art und Weise verändern kann, wie Sie Ihre Java-Programmierung schreiben und mit ihr interagieren Projekte.

Die 8 besten Java-Blogs für Programmierer

Lesen Sie weiter