Создание Javadoc на уровне пакета: package-info.java или package.html

Быстрый ответ

Для документирования пакетов в Java предпочтительнее использовать package-info.java, а не package.html. Это обусловлено поддержкой аннотаций в package-info.java, что дает большие возможности по интеграции с фреймворками и обеспечивает типобезопасность. Более того, создатели инструментов среды разработки чаще выбирают package-info.java из-за его консистентности и возможности включения тегов версий, таких как @since.

Пример:

/**
 * Ваш первый класс... а нет, это всё-таки пакет! 
 * Пакет, содержащий инструменты для апплетов и связующие интерфейсы.
 * Всегда на высоте 😎.
 *
 * @since 1.2 (Вместе с этой версией апплеты стали интереснее!)
 */
@FrameworkAnnotation // Не забудьте добавить свою аннотацию!
package com.example.applet;

import com.example.framework.FrameworkAnnotation;

Совет: Чтобы ваша документация соответствовала современным стандартам Java, используйте package-info.java. Вы будете рады этому выбору!

Почему package-info.java – лучший выбор

package-info.java стоит на верхней ступени иерархии при документировании пакетов Java благодаря его уникальным особенностям. Он предоставляет структурированную платформу для детального описания пакетов. Можно сказать, что это своеобразная "Википедия" для вашего пакета!

Аннотации для различных ситуаций: Используя package-info.java, вы можете назначать аннотации всех классам пакета. Это рационально и удобно.

Легкость восприятия: package-info.java предоставляет отдельное пространство для ваших комментариев и описаний, что упрощает поддержку кода и облегчает командную работу.

Прощай, конфликты при слиянии: Сегрегированная от кода документация упрощает контроль версий и уменьшает риск конфликтов при слиянии.

Совместимость с инструментами: package-info.java совместим с инструментами создания документации по Java, включая Javadoc.

Готовность к будущему: С развитием Java, package-info.java сохраняет свою актуальность и адаптируется к изменениям.

Пользование мощью аннотаций и тегов

Аннотации как секретный ингредиент

package-info.java позволяет прикреплять аннотации на уровне пакетов, что является значительным инструментом для интеграции с фреймворками и обеспечения типобезопасности во всем масштабе кодовой базы.

Подробнее об этом расскажет наш спикер на видео

Теги версий для сохранения истории

С использованием тегов, таких как @since, в package-info.java, вы можете документировать историю развития пакетов, что крайне важно для управления долгоживущими кодовыми базами.

Устаревшие пакеты и @Deprecated

Использование package-info.java вместе с аннотацией @Deprecated позволяет объявлять весь пакет устаревшим, напоминая разработчикам, что его использование больше не рекомендуется.

Хорошее, плохое и код

От package.html к package-info.java: Великий переход

Переход от package.html к package-info.java может показаться сложным, но он того стоит. Аннотации, поддержка инструментов и структурированная документация — веские аргументы в его пользу.

Избегайте избыточного использования аннотаций

При применении аннотаций старайтесь не дублировать их и предотвратить конфликты с аннотациями на уровне классов, чтобы не породить ошибочное поведение программы — а это настоящая головная боль для разработчика!

Актуальность документации

Что делает код понятным? Конечно же, документация пакетов, которую регулярно обновляют. При внесении изменений в код не забывайте обновлять соответствующим образом и документацию.

Визуализация

Не уверены, что выбрать для документирования ваших Java проектов: package.html или package-info.java? Вот как можно представить этот выбор:

| Подход             | Иллюстрация      |
| ------------------ | --------------- |
| `package.html`     | 🎨 Нарисованный указатель|
| `package-info.java`| 🛠 Выточенный указатель|

• 🎨 Нарисованный указатель (package.html): Приятный на вид, напоминающий старый добрый указатель, но выполняющий минимум функций.
• 🛠 Выточенный указатель (package-info.java): Это настоящий GPS-навигатор для вашего пакета, он не только предоставляет информацию, но и направляет, предупреждает и встраивается!

Хотя оба варианта обладают своими преимуществами, важно, чтобы документация выполняла больше функций, чем просто предоставление информации.

Полезные материалы

1. javadoc – Официальная Java-документация отOracle — руководство Oracle по использованию package-info.java для описания пакетов.
2. Глава 7. Пакеты – Спецификация Java SE 8 — спецификация Java, сфокусированная на пакетах, для тех, кто хочет углубить свои знания.
3. Как писать комментарии для Javadoc-инструмента – Oracle — лучшие практики написания комментариев для Javadoc, которые окажутся полезными для всей команды.
4. Задача Javadoc – Apache Ant — Разбор того, как инструмент Ant взаимодействует с Javadoc.
5. IBM Developer — Раскрытие возможностей, предлагаемых Javadoc, включая использование package-info.java.