Создание ссылок на методы в Javadoc: решение ошибок

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

Для того чтобы сослаться на метод из другого класса в Javadoc, пользуйтесь формой {@link Класс#метод}. Определение типов параметров обязательно при ссылке на перегруженные методы:

/**
 * Обратитесь к {@link OtherClass#targetMethod}.
 */

Если метод содержит параметры, формат ссылки будет выглядеть так:

/**
 * Ознакомьтесь с использованием метода {@link OtherClass#targetMethod(Type1, Type2)} здесь.
 */

Не забывайте указывать полные имена пакетов для параметров, если они не относятся к java.lang и не импортируются в ваш класс.

Подробности ссылок в Javadoc

Создание ссылок в Javadoc удобно осуществлять при помощи аннотаций @see и {@link}.

Разница между {@link} и @see

Аннотация {@link} обогащает описание деталями и является частью текста:

/**
 * Благодаря методу {@link OtherClass#method(String)} происходят чудеса.
 */

Аннотация @see добавляет ссылку в особый раздел "Смотрите также":

/**
 * @see OtherClass#method(String)
 */

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

Синтаксис и надежные подходы

С синтаксисом стоит быть осмотрительным. В случае ссылок на перегруженные методы с параметрами обязательно указывать полные имена типов:

/**
 * Для вычислений используйте {@link com.example.util.UtilityClass#complexCalculation(java.util.List, int)}.
 */

Предотвращение распространенных ошибок

Избегайте ошибок при составлении Javadoc, таких как неправильные имена методов или несоответствующие сигнатуры. Отслеживайте точность синтаксиса и актуальность информации.

Для улучшения читаемости рекомендуется добавлять описательные фрагменты вместе с {@link}:

/**
 * Для сортировки применяйте {@link java.util.Collections#sort(java.util.List) проверенный временем sort}.
 */

Советы для оптимизации ссылок в Javadoc

Грамотное включение ссылок

Тщательно встраивайте {@link} в описание, учитывая контекст:

/**
 * Метод заимствует логику у {@link OtherClass#similarMethod()}. Реально, код с характером.
 */

Определённость параметров

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

/**
 * Найдите идеи в методе {@link OtherClass#method(java.lang.String, int)}. Видно, что у него есть свои поклонники!
 */

Обработка параметров-дженериков

Для методов, использующих дженерики, обязательно использование специального синтаксиса:

/**
 * Для обработки задействован метод {@link SomeClass#<T>method(java.util.List<T>, T)}. И здесь T — в центре внимания!
 */

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

Можно представить Javadoc как указатель в "книге рецептов программиста". Каждый раздел соответствует классу, а указатель — методу:

📚 Класс A: [Закуски, Основные блюда, **Десерты**]
📚 Класс B: [**Супы**, Салаты, Напитки]

Использование ссылающегося Javadoc можно сравнить с праздничной трапезой, к которой каждый принес свое блюдо:

Суп из Класса B станет отличной добавкой к ужину Класса A 🎉🥣

Аннотация {@link} служит вашим проводником по миру кода:

/**
 * Заметьте, как {@link ClassB#soup()} оживляет наш общий стол.
 */

В мире программирования это ваш навигатор MapMyDish. Приятного вам аппетита!

Примеры для наглядности Javadoc

Наглядные примеры в Javadoc способствуют улучшению понимания методов и придают им практическую ценность.

Фрагменты кода

Используйте теги <code> или <pre> для отображения фрагментов кода:

/**
 * Создание Singleton вот так:
 * <pre>{@code
 * SingletonExample instance = SingletonExample.getTheOne();  // Вот он какой!
 * }</pre>
 */

Упоминание связанных методов

Отметьте связанную функциональность или альтернативы:

/**
 * @see OtherClass#similarMethod(). Для изучения альтернативных подходов.
 */

Пометка устаревших методов

Если метод устарел, указывайте на его замену:

/**
 * @deprecated
 * <p>Преемником стал {@link NewClass#newMethod()}</p>. Время не стоит на месте, приходит эра нового!
 */

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

1. Documentation Comment Specification for the Standard Doclet (JDK 15) — главное руководство по Javadoc от Oracle Java SE Documentation.
2. How to reference a method in javadoc? – Stack Overflow — дискуссии о методах ссылки на методы в Javadoc в сообществе разработчиков.
3. DZone – Javadoc Good Practices — обзор лучших практик написания Javadoc.
4. Java examples | DataFlavor.java — примеры использования Javadoc в реальном коде.