Jak dokumentować pakiety w Javie?

182

W interfejsach API Java widzę komentarze Javadoc dla pakietów.

Jak / gdzie umieścić komentarze Javadoc w celu udokumentowania paczki?

java packages javadoc

— jjnguy
źródło

257

Od wersji 1.5 możesz zdefiniować package-info.javaplik i podać standardowy komentarz w stylu javadoc dla pakietu:

com / foo / package-info.java:

/**
 * com.foo is a group of bar utils for operating on foo things.
 */
package com.foo;

//rest of the file is empty

Specyfikacja języka dla pakietów

— Gareth Davis
źródło

3

Bezpośredni link do specyfikacji: docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1

— gavenkoa

7

w intellij możesz kliknąć pakiet prawym przyciskiem myszy, a opcja jego utworzenia powinna znajdować się w nowym menu plików

— bsautner 30.04.2014

Znalazłem plik, który powinien znajdować się w nazwa_pakietu / src / nazwa_pakietu (wraz z resztą plików źródłowych)

— trindflo 24.04.2019

48

Aż do wersji Java 1.4 włącznie, trzeba było dostarczyć plik HTML package.html, jak opisano w innych odpowiedziach.

Od wersji 1.5 języka Java można również podać ciąg package-info.java, który zawiera regularny komentarz Javadoc (bez HTML). Ten ostatni jest preferowany, ponieważ daje kilka dodatkowych funkcji (zwłaszcza adnotacje na opakowaniu).

Szczegóły: Dokumenty Sun dotyczące javadoc

— Śleske
źródło

2

+1 za wzmiankę o obu sposobach i zasadniczą różnicę między nimi. Nawiasem mówiąc, przynajmniej IntelliJ IDEA ma obecnie lepszą obsługę pliku package.html (Ctrl-Q na nazwie pakietu pokazuje pakiet Javadocs).

— Jonik

3

Zaktualizuj mój poprzedni komentarz: obecnie IDEA obsługuje package-info.javadobrze.

— Jonik

4

Z package.htmlplikiem na poziomie pakietu (tj. W katalogu dla tego pakietu). Powinien to być w pełni sformatowany HTMLplik ze <html>zdefiniowanym znacznikiem

— oxbow_lakes
źródło

1

Więcej szczegółów? Jak powinien wyglądać plik?

— jjnguy

1

Jest to plik HTML zawierający opis twojego pakietu. Otóż to!

— oxbow_lakes

3

To stary sposób na zrobienie tego. Począwszy od Java 1.5, możesz używać package-info.java

— k2col