Czy istnieje sposób produkcji Javadoc dla podzbioru publicznych metod? Na przykład poprzez opisanie metod publicznych jako "nie będących częścią publicznego interfejsu API"

Question

Wiem, jak utworzyć Javadoc dla podzbioru klas/interfejsów/pakietów. Ale czy istnieje sposób na wyprodukowanie Javadoc tylko dla podzbioru publicznych metod?

Co wolałbym móc oznaczać metody (znacznik Javadoc lub adnotację) jako należące do określonego API lub nie być jego częścią. Następnie użyj narzędzia, które tworzy Javadoc tylko dla określonego zestawu metod - tych, które stanowią API.

Wybór między publicznym/prywatnym/pakietowym dostępem do metody nie wystarcza dla mojego projektu. Publiczna metoda może należeć do publicznego API lub nie, lub może należeć do API 1, ale nie do interfejsu API 2. Zasadniczo chciałbym móc wybrać interfejs API z dowolnego podzbioru moich publicznych metod.

Answer 1

Jeśli używasz narzędzia wiersza poleceń javadoc, możesz wykluczyć publiczne metody, oznaczając je jako Deprecated i używając opcji -nodeprecated. Ale jeśli chcesz czegoś bardziej wyrafinowanego, musisz to zaimplementować samodzielnie.

przybliżone pojęcie o tym, jak to zrobić:

1. Tworzenie niestandardowych adnotacji @ API1 @ API2 itp
2. sklasyfikować metody z tych adnotacji (tj oznaczyć je)
3. Napisz zwyczaj Zadanie antywirusowe odczytuje parametr konfiguracyjny (na przykład z pliku), który określa, do którego API należy wygenerować Javadoc.
4. Nadal w zadaniu Ant przeprowadź przez opisane metody i zastąp wszystkie adnotacje interfejsu API, które NIE są wybranym interfejsem API z przestarzałą adnotacją. Spowoduje to wykluczenie ich z Javadoc.

IMHO, to dużo kłopotów. Tak jak powiedzieli w komentarzach, jeśli masz klasę z wieloma interfejsami (dla różnych profili użytkowników, jak sądzę?), Rozważ pisanie osobnych interfejsów.

Answer 2

Jeśli nie jesteś przywiązany do javadoc, można alternatywnie spróbować Doxygen z 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 
} 

Kiedy grupa metod odpowiednio, można również ograniczyć liczbę wymaganych @cond wypowiedzi.

Włączone metody można wybrać podczas konfigurowania za pomocą opcji konfiguracji ENABLED_SECTIONS.