Java-Codedokumentation in einer separaten Dokumentdatei, die irgendwie einer Quelldatei zugeordnet ist?

8

Was wäre eine gute Alternative zur Inline-Java-Dokumentation, dh kann man eine separate Dokumentdatei haben, die irgendwie einer Java-Quelldatei zugeordnet ist?

Ich habe noch nie große Kommentarbereiche mit Code gemocht.

java documentation javadocs SD
quelle
warum brauchst du das
Mücke
1
@downvotes sieht aus wie ich die religiösen Kodierer irritiert habe :)
SD
2
Erklären Sie mir bitte, was in dieser Frage unpraktisch und unwirklich ist. Das werde ich auch zu schätzen wissen.
SD
4
Es wäre großartig, wenn Ihre Frage erklären würde, welche Probleme Sie mit Standard-Javadoc haben. Wie derzeit formuliert, ist es schwer zu sagen, ob es überhaupt ein Problem gibt, wenn man versucht, die Frage eines Ratespiels
Mücke
3
Das eigentliche Problem bei der Dokumentation von Code in einer anderen Datei besteht darin, dass die Wahrscheinlichkeit einer Aktualisierung geringer ist. Wenn sich eine Funktion ändert, wird die Dokumentation manchmal nicht immer genau aktualisiert. Wenn die Dokumentation in eine andere Datei verschoben wird, gibt es jetzt einen zusätzlichen Schritt, um die richtige Änderung vorzunehmen. Es macht auch weniger offensichtlich, dass die Dokumentation falsch ist. Sie sehen es nur, wenn Sie sich die Dokumentation genauer ansehen, nicht, wenn Sie im Code einen Bildlauf durchführen.
Unholysampler

Antworten:

8

Ich habe die Javadoc-Funktion von Paketkommentaren verwendet , um zu vermeiden, dass Quellcode mit ausführlichen Dokumentationskommentaren verschmutzt wird:

Kommentare auf Paketebene

In Javadoc 1.2 sind Dokumentkommentare auf Paketebene verfügbar. Jedes Paket kann eine eigene Dokumentkommentar-Quelldatei auf Paketebene haben, die das Javadoc-Tool in die von ihm erstellte Dokumentation einfügt. Diese Datei hat den Namen package.html(und ist für alle Pakete gleich). Diese Datei wird zusammen mit allen *.javaDateien im Quellverzeichnis gespeichert. (Legen Sie die packages.htmlDatei nicht im neuen Quellverzeichnis von doc-files ab, da diese Dateien nur in das Ziel kopiert und nicht verarbeitet werden.)

Die Datei package.html ist ein Beispiel für eine Quelldatei auf Paketebene für java.textund package-summary.html ist die Datei, die das Javadoc-Tool generiert.

Das Javadoc-Tool verarbeitet package.htmldrei Dinge ...

Mit der obigen Funktion hatte ich eine ausführliche Dokumentation für Klassen und Methoden in dem Paket, das separat vom Code in einer dedizierten HTML-Datei gespeichert war. Was Javadoc-Kommentare in Java-Dateien betrifft, habe ich dort nur kurze Erklärungen geschrieben und Text wie hinzugefügt

Weitere Informationen finden Sie bei Bedarf in der Paketdokumentation.

Eine Sache, die mir besonders gut gefallen hat, war, dass Dokumente zwar in einer separaten Datei und in einem für große Dokumente (HTML) bequemeren Format vorliegen, jedoch nahe genug am zugehörigen Quellcode gespeichert wurden und alle darin enthaltenen Aktualisierungen während des Vorgangs automatisch abgerufen wurden der Build.

Ab Java 1.5 können Sie alternativ a package-info.javazusammen mit den Klassen des Pakets einfügen. Diese Datei sollte folgendermaßen aussehen:

/**
 * Javadoc for your package here
 */
package com.yourpackage;

Die JLS-Dokumentation legt nahe, dass dies der bevorzugte Weg ist:

Das folgende Schema wird für dateisystembasierte Implementierungen dringend empfohlen: Die einzige kommentierte Paketdeklaration wird, falls vorhanden, in einer Quelldatei abgelegt, die package-info.javain dem Verzeichnis aufgerufen wird, das die Quelldateien für das Paket enthält ...

Es wird empfohlen package-info.java, bei Vorhandensein von package.htmljavadoc und anderen ähnlichen Dokumentationsgenerierungssystemen den Platz einzunehmen . Wenn diese Datei vorhanden ist, sollte das Dokumentationserstellungstool unmittelbar vor der (möglicherweise kommentierten) Paketdeklaration in package-info.java nach dem Kommentar zur Paketdokumentation suchen. Auf diese Weise package-info.javawird das einzige Repository für Anmerkungen und Dokumentationen auf Paketebene. Wenn es in Zukunft wünschenswert wird, andere Informationen auf Paketebene hinzuzufügen, sollte sich diese Datei als geeignetes Zuhause für diese Informationen erweisen.

Mücke
quelle
Wie finden Sie package-info.java aus der Perspektive des tatsächlichen Schreibens von Text, HTML-Tags, Javadoc-Schlüsselwörtern usw.? Ist es klobig oder ist es kein Problem?
Adam