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

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

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

Пример:

Java

Скопировать код

/**
 * Ваш первый класс... а нет, это всё-таки пакет! 
 * Пакет, содержащий инструменты для апплетов и связующие интерфейсы.
 * Всегда на высоте 😎.
 *
 * @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? Вот как можно представить этот выбор:

Markdown