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

230

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

package-info.java

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

package.html

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

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

java javadoc TheLQ
источник
46
package-info.javaможет содержать аннотации [пакета] - это не обязательно все документы API.
Том Хотин -
52
Я бы не квалифицировал package-info.java как злоупотребление классом. Это исходный файл Java (с расширением «.java»), но это не файл класса, потому что он не содержит объявления класса. И, фактически, он не может содержать объявление класса, потому что «package-info» не является допустимым именем класса.
Скрабби
19
Другая причина использования package-info.java вместо package.html может заключаться в том, что .java не подразумевает особый формат вывода документации. Например, вы можете вывести Javadoc в виде LaTeX или в виде файла PDF. В зависимости от реализации компилятора javadoc это может вызвать проблемы в случае .html.
honeyp0t
3
На самом деле @Scrubbie - хотя вы должны быть правы, я думаю, вы можете указать там закрытые для пакета классы. :-( Я согласен с вашим мнением, хотя использование package-info.javaJavadoc и аннотаций не является злоупотреблением классом.
mjaggard
2
@JonasN см stackoverflow.com/a/14708381/751579 (я знаю , что ты имел эту проблему 3 -х лет назад, но , возможно , кто - то нуждается в верхушку сейчас)
davidbak

Ответы:

269

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

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

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

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

trashgod
источник
3
Любая конкретная причина, почему его предпочитают?
TheLQ
2
@TheLQ: Я предполагаю аннотации пакетов, поскольку у компилятора есть больше информации для работы; больше выше.
trashgod
3
Пакетные аннотации являются новыми для меня и кажутся хорошей причиной для package-info.java из-за его объема.
укладчик
6
Отредактируйте ответ немного подробнее: объясните «аннотацию пакета» - аннотацию, которая должна применяться ко всем классам в пакете или иным образом к пакетам в целом. Ссылка tech.puredanger.com была единственной, которая действительно объясняет, почему я должен заботиться. Тем не менее, это хорошая, полезная ссылка.
Roboprog
5
используя package-info.java, вы можете использовать {@link} и другие доклеты. Когда вы связываете класс java.lang, когда генерируется javadoc, вы автоматически получаете {@link}, указывающий на онлайн-javadoc класса, соответствующего используемому вами jdk; Ide может также помочь обнаружить неправильные ссылки при рефакторинге рефакторинга.
Луиджи Р. Виджано