Как добавить комментарии на уровне пакета в Javadoc?

Я использую Check-Style, FindBugs и PMD для проверки кода Java. Я исправил почти все ошибки, обнаруженные этими инструментами.

Я не могу понять, как написать "комментарий к пакету", который является ошибкой, обнаруженной при помощи checkstyle. Я просмотрел документацию Check-Style, но я этого не понимаю.

Может ли кто-нибудь помочь мне написать комментарий на уровне пакета в Java?

Ответ 1

Комментарии javadoc на уровне пакетов помещаются в файл с именем package-info.java внутри каталога пакета. Он содержит комментарий и объявление пакета:

/**
 * Provides the classes necessary to create an applet and the classes an applet uses 
 * to communicate with its applet context. 
 * <p>
 * The applet framework involves two entities: 
 * the applet and the applet context. An applet is an embeddable window (see the 
 * {@link java.awt.Panel} class) with a few extra methods that the applet context 
 * can use to initialize, start, and stop the applet.
 *
 * @since 1.0
 * @see java.awt
 */
package java.lang.applet;

Это описано здесь: Файлы комментариев пакета

Ответ 2

Создайте файл package-info.java в своем пакете для документа
Добавить дескриптор пакета
Добавить комментарий (/**... */) перед объявлением пакета

Следующая ссылка содержит дополнительную информацию: http://docs.oracle.com/javase/specs/jls/se5.0/html/packages.html

Рекомендуется, чтобы package-info.java, если он присутствует, замените package.html на javadoc и другие подобные системы создания документации

Аннотации к пакету также будут объявлены на странице package-info.java

Greetz, GHAD

Ответ 3

Вам нужно сделать страницу package.html, расположенную внутри пакета. Вы можете прочитать о содержании и структуре этого файла в Как написать комментарии к Doc для страницы инструмента Javadoc.

Ответ 4

Существует два способа добавления документации уровня пакета с помощью javadoc:

package-info.java
- Только с 5.0
- Предпочтительный способ
- Может содержать объявление пакета, аннотации пакетов, комментарии к пакетам и теги Javadoc
package.html
- Любая версия Java
- Может не содержать объявление пакета и/или аннотации пакетов

Подробнее и примеры здесь. Какой из них использовать: Javadoc: package.html или package-info.java

Ответ 5

Google нашел это как первый хит:

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#packagecomments

Вы просто создаете файл с именем package.html в каждом пакете.

Ответ 6

Используя package.html файл для комментариев. См. Этот документ: Как написать комментарии к Doc для инструмента Javadoc.

Ответ 7

Вы можете добавить документацию на уровне пакета.

От Документация Sun:

Как правило, package-info.java содержит только объявление пакета, которому сразу предшествуют аннотации пакета. Несмотря на то, что файл может содержать исходный код для одного или нескольких классов с закрытым пакетом, это будет очень плохая форма.

Рекомендуется, чтобы package-info.java, если он присутствует, заменил package.html для javadoc и других подобных систем генерации документации. Если этот файл присутствует, инструмент создания документации должен искать комментарий к документации пакета непосредственно перед объявлением пакета (возможно, аннотированного) в package-info.java. Таким образом, package-info.java становится единственным репозиторием для аннотаций и документации уровня пакета. Если в будущем будет желательно добавить любую другую информацию на уровне пакета, этот файл должен оказаться удобным для этой информации.