Як документувати пакети на Java?

182

У API Java я бачу коментарі Javadoc для пакетів.

Як / де розміщувати коментарі Javadoc для документування пакету?

java packages javadoc

— jjnguy
джерело

257

З 1.5 ви можете визначити package-info.javaфайл та надати стандартний коментар у стилі javadoc для пакету:

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

Специфікація мови для пакетів

— Гарет Девіс
джерело

3

Пряме посилання на spec: docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1

— gavenkoa

7

в Intellij ви можете клацнути правою кнопкою миші на пакет, і можливість створити це має бути в новому меню файлів

— bsautner

Я знайшов файл, який повинен

— містити ім'я пакета

48

До Java 1.4, включаючи Java, ви мали надати HTML-файл package.html, як описано в інших відповідях.

Оскільки Java 1.5 ви також можете надати package-info.java, який містить звичайний коментар Javadoc (без HTML). Останнє є кращим, оскільки воно надає деякі додаткові можливості (зокрема, анотації до пакетів).

Докладніше: Документи Sun для javadoc

— sleske
джерело

2

+1 для згадування обох способів та суттєвої різниці між ними. До речі, принаймні IntelliJ IDEA в даний час має кращу підтримку package.html (Ctrl-Q у назві пакета відображається пакет Javadocs).

— Jonik

3

Оновлення до мого попереднього коментаря: сьогодні IDEA підтримує package-info.javaчудово.

— Jonik

4

З package.htmlфайлом на рівні пакету (тобто в каталозі цього пакету). Це повинен бути повністю сформований HTMLфайл, у якому <html>визначений тег

— oxbow_lakes
джерело

1

Детальніше? Як має виглядати файл?

— jjnguy

1

Це HTML-файл, що містить опис вашого пакета. Це воно!

— oxbow_lakes

3

Це старий спосіб зробити це. З Java 1.5 ви можете скористатися

— package-info.java