Ссылка на значения Enum в Javadoc: Решение с {@link Planet}

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

Для создания ссылки на значение перечисления в Javadoc следует использовать запись {@link EnumType#ENUM_VALUE}. Вот пример:

/**
 * Проверяет функцию "всё ещё в кровати" с помощью {@link DayOfWeek#SUNDAY}.
 */
public void checkWeekend() {
    // Код выполнится, если тепло одеяла не отпускает 😴
}

В этой строке DayOfWeek является требуемым типом перечисления, а SUNDAY — это соответствующее значение.

Предоставление корректного контекста для перечислений

Указывайте полностью квалифицированное имя перечисления в том случае, если оно не импортировано в класс:

/**
 * Понедельник — начало рабочей недели:
 * {@link java.time.DayOfWeek#MONDAY}.
 */

Такой подход исключит вероятность путаницы при работе с Javadoc, особенно это важно в документации, предназначенной для сторонних пользователей.

Навигация по импортам в IDE

Если вы используете Eclipse, воспользуйтесь комбинацией клавиш:

• Ctrl + Shift + O (PC) или Cmd + Shift + O (Mac) для управления импортами. Будьте властелином вашей среды разработки. 🚀

Ссылки на значения перечислений: лучшие практики

• Единый стиль: Следуйте единому стилю оформления документации.
• Тестирование: Убедитесь, что ссылки в сгенерированном Javadoc работают корректно.
• Совместимость: Проверьте совместимость вашей версии JDK с используемым синтаксисом @link.

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

Представьте наш код как тематический парк с аттракционами:

Перечисление Park (🎠): [MONDAY 🎢, TUESDAY 🎡, WEDNESDAY 🏰]

Пример использования @link со значением перечисления:

/**
 * Планирование посещения в среду:
 * {@link EnumPark#WEDNESDAY} 🏰 – не забудьте костюм принцессы!
 */

Мгновенный переход к нужному месту в парке аттракционов нашего кода!

Link или See: различные пути перехода к цели

Иногда предпочтительнее использовать @see, а не @link:

/**
 * Главный метод.
 * @see DayOfWeek#MONDAY потому что начало рабочей недели – это понедельник, верно?
 */
public static void main(String[] args) {
    // А почему программист не может идти на работу?
    // Он не смог "разобраться" с массивами! 😉
}

Тег @see создает раздел "Смотрите также" в Javadoc, что удобно для указания дополнительной информации.

Устранение проблем и работа с кодом "детективом"

Будьте внимательны к следующим моментам:

• Неработающие ссылки: Удостоверьтесь, что нужное перечисление существует и доступно публично.
• Ошибки при генерации Javadoc: Проверьте правильность использования Javadoc.
• Устаревшие ссылки: Обновляйте документацию в соответствии с актуальным состоянием кода. Соответствующий подход можно сравнить с выбором пары носков!

Расширяем границы

Для обеспечения корректного контекста документации не забывайте:

• Размещать описание вокруг ссылок для большей ясности.
• Указывать роль или связь упомянутого элемента в документации.

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

1. Javadoc в документации Oracle — Обращение к перечислениям через Javadoc.
2. Обсуждение вопроса о @link и Enums на Stack Overflow — Опыт экспертов сообщества.
3. Создание Doc-комментариев для Javadoc от создателей Java.
4. Детальное объяснение связи Java Enums и Javadoc.
5. Javadoc в обучающем руководстве от Tutorialspoint.