Javadoc: package.html или package-info.java

Question

При попытке создания комментариев Javadoc на уровне пакета, какой метод предпочтительнее? Что ты делаешь?

package-info.java

• Pros
  • Новые
• Cons
  • Злоупотребление классом - классы для кода, а не только для комментариев

package.html

• Pros
  • Расширение HTML означает, что это не код
  • Подсветка синтаксиса в IDE / текстовых редакторах
• Cons
  • Отсутствует

---

Для меня я всегда использовал Package.html. Но мне интересно, если это правильный выбор.

Answer 1

package-info.java: «Этот файл является новым в JDK 5.0 и предпочтительнее, чем package.html.» - javadoc - Генератор документации Java API

Приложение: Большая разница, кажется, аннотаций пакетов .Есть еще несколько способов обоснования в 7.4 Декларации пакета .

Добавление: функция аннотации также упоминается здесь и здесь .

Приложение: См. также Для чего package-info.java? 1025 *.