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

Odpowiedzi:

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