Ich verwende Javadocs, die von der Ant-Task javadoc generiert werden, um einen Webdienst zu dokumentieren, und ich möchte einige Konstruktoren von der Ausgabe ausschließen. Wie mache ich das?Wie schließe ich eine bestimmte Methode/Konstruktor von den Ergebnissen der javadoc Ant-Aufgabe aus?
Siehe die relevanten Javadoc FAQ entry.
Es gibt derzeit keine Javadoc Option zu verstecken, ausschließen oder öffentliche Mitglieder aus der javadoc generierten Dokumentation unterdrücken.
Es scheint dies in dem Vanille Javadoc nicht möglich ist, aber einige Abhilfen angeboten.
Ändern der Methode Zugriffsebene des Verfahrens, dann verwenden Sie die Verwendung der Zugriffsebene Filterung der javadoc Aufgabe Attribute, private, package usw. Nur dies tun, wenn es sinnvoll, in Ihrem Code macht, wenn, zum Beispiel Verfahren, das hatte unangemessen lockere Zugriffsstufen.
Für Konstruktoren können Sie beispielsweise die Zugriffsebene auf package reduzieren und dann eine Factory-Klasse in demselben Paket erstellen, das den Konstruktionszugriff außerhalb des Pakets ermöglicht. Die Factory-Klasse kann leicht aus den Javadocs gefiltert werden. Art von Hacky, aber es funktioniert.
Es gibt keine Möglichkeit, dies für öffentliche Methoden zu tun. Die gängige Praxis (selbst in einigen JDK-Klassen) besteht darin, anzugeben, dass die Methode oder der Konstruktor nicht für die öffentliche Verwendung gedacht ist.
Es gibt eine plan to add an @exclude tag in the future:
@exclude - für API von Generation von Javadoc- ausgeschlossen werden. Programmierer würde eine Klasse, Schnittstelle, Konstruktor, Methode oder Feld mit @exclude markieren. Das Vorhandensein des Tags würde dazu führen, dass die API aus der generierten Dokumentation ausgeschlossen wird. Das folgende Text-Tag könnte den Grund für den Ausschluss erklären, , würde aber von Javadoc ignoriert werden. (. Früher als @hide vorgeschlagen, aber die Begriff „verstecken“ ist besser geeignet für Laufzeit dynamisch ein-/ausblenden Fähigkeit) Weitere Diskussion siehe: Feature Request #4058216 in Developer Verbindung.
Chris Geben Nøkleberg der ExcludeDoclet einen Versuch: http://www.sixlegs.com/blog/java/exclude-javadoc-tag.html
Ich habe mit ihm nur experimentiert und es scheint, den Trick zu tun.
Ist etwas öffentliches aus Ihrer Dokumentation nicht nur eine Variation von "Sicherheit durch Obskurität" (oder besser: "Dokumentation durch Unklarheit")? Wenn der Konstruktor Teil der API Ihres Codes ist, steht er ihnen zur Verfügung. Wenn sie davon erfahren und es benutzen, ist das ihre Schuld (seit Sie es überhaupt veröffentlicht haben)?
Wenn Sie die Sichtbarkeit des Konstruktors ändern oder es vollständig entfernen können, würde ich dafür gehen. Wenn Sie es nicht aus der API entfernen können, machen Sie es im Javadoc für den Konstruktor bekannt, dass es nicht für die Verwendung über den Webdienst vorgesehen ist.Auf diese Weise haben Sie einen Vertrag mit den Nutzern Ihrer API geschlossen und sie darüber informiert, dass Sie sie nicht verwenden dürfen.
Es ist besser zu dokumentieren, dass es nicht verwendet werden sollte, anstatt es überhaupt nicht zu dokumentieren (wenn es öffentlich ist). Wenn Sie es nicht dokumentieren, erhöht sich das Risiko, dass es unbeabsichtigt verwendet wird, und dann bricht der Clientcode, der es verwendet, ab, wenn Sie die Implementierung ändern.
Derzeit ist die einfachste Lösung, den Javadoc-Kommentar mit @deprecated zu starten und dann -nodeprecated an den Befehl javadoc zu übergeben. Dies ist natürlich nicht akzeptabel, wenn Sie tatsächlich veraltete Artikel haben, die Sie dennoch in die Dokumentation aufnehmen möchten.
Das Schließen, das ich bekam, ist, Doclava zu verwenden, das das @hide-Tag hat, das Sie in Methodendokumentation spezifizieren können.
Um zu verhindern, dass parametrisierte Typen nicht gut dokumentiert werden, überprüfen Sie diese Korrektur von ExcludeDoclet https://sdgsystems.com/blog/hiding-javadoc-elements-exclude-tag – antgar9