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