В Java API я могу видеть комментарии Javadoc для пакетов.
Как/где разместить комментарии Javadoc для документирования пакета?
Начиная с 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
До Java 1.4 включительно, вы должны были предоставить файл HTML package.html, как описано в других ответах.
Начиная с Java 1.5 вы также можете предоставить package-info.java, который содержит обычный комментарий Javadoc (без HTML). Последний вариант предпочтителен, так как он дает вам некоторые дополнительные функции (в частности, аннотации пакетов).
Подробности: Sun документы для Javadoc
С файлом package.html на уровне пакета (т.е. в каталоге для этого пакета). Это должен быть полностью сформированный файл HTML с тегом <html>, определенным в нем