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

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

package-info.java

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

package.html

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

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

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

Добавление: Большая разница, по-видимому, представляет собой annotations пакетов . В 7.4 объяснения пакетов есть немного больше.

Приложение: примечание также упоминается здесь и здесь .

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

  • Создание JavaDocs с плагином Android Gradle
  • Как добавить документацию API Java в Eclipse?
  • Eclipse: присоединить источник / javadoc к библиотеке через локальное свойство
  • Давайте будем гением компьютера.