Как мне документировать пакеты в 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

Прямая ссылка на спецификацию: docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1

— gavenkoa

7

в intellij вы можете щелкнуть правой кнопкой мыши на пакете, и возможность создать его должна быть в новом меню файла

— bsautner

Я обнаружил, что файл должен быть в packagename / src / packagename (с остальными исходными файлами)

— trindflo

48

До Java 1.4 включительно, вы должны были предоставить файл HTML package.html, как описано в других ответах.

Начиная с Java 1.5 вы также можете предоставить a package-info.java, который содержит обычный комментарий Javadoc (без HTML). Последний вариант предпочтителен, так как он дает вам некоторые дополнительные функции (в частности, аннотации пакетов).

Детали: документы Sun для Javadoc

— sleske
источник

2

+1 за упоминание обоих путей и существенную разницу между ними. Кстати, по крайней мере IntelliJ IDEA в настоящее время имеет лучшую поддержку package.html (Ctrl-Q на имени пакета показывает Javadocs пакета).

— Джоник

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

— k2col