Używam javadocs generowanych przez zadanie Ant Antivirus javadoc do udokumentowania usługi WWW i chcę wykluczyć niektóre konstruktory z danych wyjściowych. Jak mogę to zrobić?Jak wykluczyć określoną metodę/konstruktora z wyników zadania Ant javadoc?
Zobacz odpowiednie Javadoc FAQ entry.
Obecnie nie ma opcji Javadoc ukryć, stłumić lub wykluczyć publicznych członków z javadoc generowane dokumentacji.
Wydawałoby się, nie jest to możliwe w wanilia Javadoc, ale niektóre obejścia są oferowane.
zmienić poziom dostępu metoda metody, a następnie użyć użyć atrybutów filtrowanie dostępu wypoziomowania javadoc zadania należy private, package itd Tylko to zrobić, jeśli ma to sens w kodzie, choć np metoda, która miała niepoprawnie luźne poziomy dostępu.
Dla konstruktorów można na przykład zmniejszyć poziom dostępu do package, a następnie utworzyć klasę fabryczną w tym samym pakiecie, który zapewnia dostęp do budowy poza pakietem. Klasę fabryczną można łatwo filtrować z javadocs. Coś w stylu hacky, ale działa.
Nie można tego zrobić w przypadku publicznych metod. Standardową praktyką (nawet w kilku klasach JDK) jest wskazanie, że metoda lub konstruktor nie jest przeznaczona do użytku publicznego.
Jest plan to add an @exclude tag in the future:
@exclude - dla API mają być wyłączone z generacji przez Javadoc. Programista wyznaczy klasę, interfejs, konstruktora, metodę lub pole z @exclude. Obecność tagu spowodowałaby wyłączenie interfejsu API z wygenerowanej dokumentacji . Tekst następujący po tagu mógłby wyjaśnić przyczynę wykluczenia, , ale zostałby zignorowany przez Javadoc. (. Dawniej zaproponowany jako @hide, ale Określenie "hide" jest bardziej odpowiedni dla run-time dynamicznego pokazać/ukryć możliwości) Aby uzyskać więcej dyskusji, patrz: Feature Request #4058216 w Developer Connection.
Daj Chris Nokleberg za ExcludeDoclet spróbować: http://www.sixlegs.com/blog/java/exclude-javadoc-tag.html
Właśnie eksperymentowałem z nim i wydaje rade.
Czy wykluczenie czegoś publicznego z twojej dokumentacji jest tylko odmianą "bezpieczeństwa przez zaciemnienie" (czy raczej "dokumentacja przez zaciemnienie")? Jeśli konstruktor jest częścią interfejsu API twojego kodu, jest on dostępny do użycia. Jeśli dowiedzą się o tym i będą z niego korzystać, czy to ich wina (skoro upubliczniłaś je w pierwszej kolejności)?
Jeśli możesz zmienić widoczność konstruktora lub go całkowicie usunąć, poszedłbym po to. Jeśli nie możesz usunąć go z interfejsu API, poinformuj go w dokumentacji Javadoc, że nie jest przeznaczony do używania przez usługę internetową.W ten sposób zawarłeś umowę z użytkownikami swojego API, informując o tym, aby jej nie używać.
Lepiej jest udokumentować, że nie należy go używać zamiast go nie dokumentować (jeśli jest publiczny). Nieudokumentowanie go zwiększa ryzyko, że zostanie ono przypadkowo użyte, a następnie kod klienta, który go używa, ulega przerwaniu po zmianie implementacji.
Obecnie najprostszym rozwiązaniem jest uruchomienie komentarza javadoc za pomocą @deprecated, a następnie przekazanie -nodeprecated do polecenia javadoc. Oczywiście może to być niedopuszczalne, jeśli masz faktycznie wycofane elementy, które mimo to chcesz uwzględnić w dokumentacji.
Zamknięcia, które otrzymałem, to użycie Doclava, który ma znacznik @hide, który można określić w dokumentacji metody.
Aby zapobiec nieuprawnionemu udokumentowaniu typów sparametryzowanych, należy sprawdzić tę korektę ExcludeDoclet https://sdgsystems.com/blog/hiding-javadoc-elements-exclude-tag – antgar9