Gibt es eine Möglichkeit, Javadoc für eine Teilmenge öffentlicher Methoden zu erstellen? Zum Beispiel, indem ich öffentliche Methoden als "nicht Teil der öffentlichen API" beschreibe

Question

Ich weiß, wie man Javadoc für eine Teilmenge von Klassen/Schnittstellen/Paketen erzeugt. Aber gibt es eine Möglichkeit, Javadoc nur für eine Teilmenge der öffentlichen Methoden zu produzieren?

Was ich bevorzugen würde ist in der Lage, Methoden (Javadoc-Tag oder Annotation) als zu einer bestimmten API gehören oder nicht Teil davon sein. Dann haben Sie ein Werkzeug, das Javadoc nur für die angegebene Menge von Methoden erzeugt - diejenigen, die die API bilden.

Die Wahl zwischen öffentlich/privat/Paket Zugriff auf eine Methode ist nicht genug für mein Projekt. Eine öffentliche Methode kann zu einer öffentlichen API gehören oder nicht, oder sie kann zu API 1, aber nicht zu API 2 gehören. Im Wesentlichen möchte ich die API aus einer beliebigen Teilmenge meiner öffentlichen Methoden auswählen können.

Answer 1

Wenn Sie das Befehlszeilentool javadoc verwenden, können Sie öffentliche Methoden ausschließen, indem Sie sie als Deprecated markieren und die Option -nodeprecated verwenden. Aber wenn Sie etwas anspruchsvolleres wollen, müssen Sie es selbst implementieren.

Eine grobe Idee, wie man es tun:

1. individuelle Anmerkungen @ API1, @ API2 erstellen usw.
2. Klassifizieren Sie Ihre Methoden mit den Anmerkungen (dh sie markieren)
3. eine benutzerdefinierte schreiben Ant-Task, der einen Konfigurationsparameter liest (z. B. aus einer Datei), der angibt, für welche API Sie das Javadoc generieren möchten.
4. Immer noch in der Ant-Aufgabe, durchlaufen Sie die mit Annotationen versehenen Methoden und ersetzen Sie alle API-Annotationen, die NICHT die ausgewählte API sind, mit der Annullierten Annotation. Dies wird sie von Javadoc ausschließen.

IMHO, das ist eine Menge Ärger. Wie Sie in den Kommentaren sagten, wenn Sie eine Klasse mit mehreren Schnittstellen (für verschiedene Benutzerprofile, denke ich?) Haben, sollten Sie separate Schnittstellen schreiben.

Answer 2

Wenn Sie nicht zu javadoc gebunden sind, können Sie alternativ versuchen Doxygen mit conditional sections:

public class SomeClass { 
    /// @cond API1 
    /** 
    * This method can be called as part of API1 only. 
    */ 
    public void method() { ... } 
    /// @endcond 

    /// @cond (API1 || API2) 
    /** 
    * This method can be called as part of API1 or API2. 
    */ 
    public void method2() { ... } 
    /// @endcond 
} 

Wenn Sie Gruppe die Methoden entsprechend, können Sie auch die Anzahl der erforderlichen @cond Aussagen beschränken.

Die Methoden, die tatsächlich enthalten sind, können dann beim Erstellen der Dokumentation über die Konfigurationsoption ENABLED_SECTIONS ausgewählt werden.