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

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

package-info.java

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

package.html

  • Pros
    • Расширение HTML означает его не код
    • Выделение синтаксиса в редакторах IDE/текстовых редакторах
  • Cons
    • None

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

Ответы

Ответ 1

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

Добавление: Большая разница, кажется, аннотации пакетов. Там немного больше на пути к обоснованию в 7.4. Объявления пакетов.

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

Приложение: См. также Декларативное программирование в Java: аннотации на уровне пакетов.