Javadoc: package.html або package-info.java

230

При спробі створити коментарі Javadoc на рівні пакету, що є кращим методом? Що ти робиш?

package-info.java

Плюси
- Новіші
Мінуси
- Зловживання класом - Класи призначені для коду, а не лише для коментарів

package.html

Плюси
- Розширення HTML означає його не код
- Підсвічування синтаксису в редакторах IDE / тексту
Мінуси
- Немає?

Для мене я завжди використовував Package.html. Але мені цікаво, чи це правильний вибір.

java javadoc

— TheLQ
джерело

package-info.javaможе містити анотації [пакет] - це не обов'язково всі документи API.

— Том Хотін - тайклін

Я б не кваліфікував package-info.java як зловживання класом. Це вихідний файл Java (має розширення файлу ".java"), але це не файл класу, оскільки він не містить декларації класу. І насправді він не може містити декларацію класу, оскільки "інформація-пакет" не є юридичною назвою класу.

— Скрубі

Іншою причиною використання package-info.java замість package.html може бути те, що .java не передбачає конкретного вихідного формату документації. Наприклад, ви можете вивести javadoc у вигляді LaTeX або як PDF-файл. Залежно від реалізації компілятора javadoc, це може спричинити проблеми у випадку .html.

— honeyp0t

Насправді @Scrubbie - хоча ти маєш рацію, я думаю, що ти можеш вказати там приватно-приватні класи. :-( Я погоджуюся з вашими настроями, хоча використання package-info.javaдля Javadoc та анотацій не є зловживанням класом.

— mjaggard

@JonasN см stackoverflow.com/a/14708381/751579 (я знаю , що ти мав цю проблему 3 -х років тому, але , можливо , хтось - то потребує в верхівку зараз)

— davidbak

269

package-info.java: "Цей файл є новим у JDK 5.0, і він є кращим над package.html." - javadoc - Генератор документації Java API

Додаток: Велика різниця, схоже, полягає в анотаціях на упаковці . У деклараціях 7.4 про упаковку є дещо більше .

Додаток: Функція анотації також згадується тут і тут .

Додаток: Дивіться також Що package-info.javaдля чого? .

— trashgod
джерело

Якась конкретна причина, чому її віддають перевагу?

— TheLQ

@TheLQ: я здогадуюсь анотацій щодо пакета, оскільки компілятор має більше інформації для роботи; більше вище.

— trashgod

Анотації щодо пакетів для мене є новими, і, здається, є вагомою причиною для пакета-info.java завдяки його обсягу.

— укладальник

Відредагуйте відповідь ще трохи: поясніть "анотація до пакета" - примітка, яка повинна застосовуватися до всіх класів у пакеті чи іншим чином до пакетів у цілому. Посилання tech.puredanger.com було єдиним, хто насправді пояснив, чому я повинен піклуватися. Це сказало, що це гарне, корисне посилання.

— Робопрог

використовуючи package-info.java, ви можете використовувати {@link} та інші доклети. Коли ви зв'язуєте клас java.lang, коли javadoc генерується, ви автоматично отримуєте {@link}, що вказує на онлайн-javadoc класу, що відповідає jdk, який ви використовуєте; ide також може допомогти виявити неправильні посилання, коли ви робите рефакторинг рефакторингу.

— Луїджі Р. Віджіано