Тег @link в Javadoc: руководство по ссылкам на методы
Узнайте, как правильно использовать тег @link в Javadoc для создания ссылок на методы. Освойте синтаксис для ссылок на методы в том же классе, в других классах и для цепочек вызовов методов с практическими примерами.
Как правильно ссылаться на метод в Javadoc с помощью тега @link?
Я пытаюсь понять, как форматировать тег @link в Javadoc для создания ссылок на методы. Конкретно, я хочу преобразовать эту документацию:
/**
* Returns the Baz object owned by the Bar object owned by Foo owned by this.
* A convenience method, equivalent to getFoo().getBar().getBaz()
* @return baz
*/
public Baz fooBarBaz()
В эту:
/**
* Returns the Baz object owned by the Bar object owned by Foo owned by this.
* A convenience method, equivalent to {@link getFoo()}.{@link getBar()}.{@link getBaz()}
* @return baz
*/
public Baz fooBarBaz()
Но я не уверен насчет правильного синтаксиса для тега @link при ссылке на методы.
Содержание
- Базовый синтаксис @link
- Ссылки на методы в том же классе
- Ссылки на методы в других классах
- Ссылки на цепочки методов
- Параметры методов и перегруженные методы
- Лучшие практики и распространенные ошибки
- Продвинутые примеры
Базовый синтаксис @link
Основной синтаксис для тега @link:
{@link className#methodName()}
Согласно документации Oracle Javadoc, этот тег создает встроенные гиперссылки в комментариях документации, аналогично тому, как работает @see, но встроенный непосредственно в текст.
Ключевые компоненты:
className: Полное имя класса или пакета#: Разделитель между классом и методомmethodName(): Имя метода со скобками
Для методов скобки обязательны, даже если параметры отсутствуют. Как отмечено в исследованиях, “Синтаксис для path_to_member различается в зависимости от того, находится ли метод, на который мы ссылаемся, в том же классе или нет.” источник
Ссылки на методы в том же классе
При ссылке на методы в том же классе можно использовать сокращенную нотацию с префиксом #:
/**
* Удобный метод, возвращающий текущего пользователя
* @return объект текущего пользователя
* @see #getCurrentUser()
*/
public User getActiveUser() {
return getCurrentUser();
}
/**
* Получает текущего аутентифицированного пользователя
* @return текущего пользователя
*/
public User getCurrentUser() {
// реализация
}
Символ # указывает, что метод принадлежит текущему классу. Этот синтаксис более чистый и лаконичный, чем повторение имени класса.
Ссылки на методы в других классах
Для методов в других классах необходимо указать полное имя класса:
/**
* Проверяет пользовательский ввод в соответствии с правилами сервиса
* Использует {@link com.example.validation.UserValidator#validateInput(String)}
* для выполнения проверки
* @param вводимые данные пользователя для проверки
* @return true, если данные корректны, иначе false
*/
public boolean validate(String input) {
return UserValidator.validateInput(input);
}
Если класс импортирован, можно использовать только имя класса:
import java.util.List;
/**
* Обрабатывает элементы с помощью утилитарного метода
* Вызывает {@link Collections#sort(List)} для сортировки элементов
* @param элементы для сортировки
*/
public void processItems(List<String> items) {
Collections.sort(items);
}
Ссылки на цепочки методов
Для цепочек вызовов методов, таких как getFoo().getBar().getBaz(), можно создать отдельные ссылки для каждого метода:
/**
* Возвращает объект Baz, принадлежащий объекту Bar, который принадлежит Foo,
* который принадлежит данному объекту.
* Удобный метод, эквивалентный {@link #getFoo()}.{@link #getBar()}.{@link #getBaz()}
* @return baz
*/
public Baz fooBarBaz() {
return getFoo().getBar().getBaz();
}
Каждый метод в цепочке получает свой собственный тег @link. Разделители-точки между вызовами методов остаются вне тегов для поддержания правильного синтаксиса.
Параметры методов и перегруженные методы
При ссылке на методы с параметрами включайте типы параметров для различения перегруженных методов:
/**
* Создает нового пользователя с указанными деталями
* Вызывает {@link UserService#createUser(String, int, boolean)}
* @param username имя пользователя
* @param возраст пользователя
* @param isActive активен ли пользователь
* @return созданный пользователь
*/
public User createUserAccount(String username, int age, boolean isActive) {
return UserService.createUser(username, age, isActive);
}
Для методов со сложными параметрами можно использовать имена типов параметров:
/**
* Обрабатывает платеж с использованием указанного метода
* Использует {@link PaymentProcessor#processPayment(PaymentMethod, BigDecimal)}
* @param метод оплаты для использования
* @param сумма платежа
*/
public void makePayment(PaymentMethod method, BigDecimal amount) {
PaymentProcessor.processPayment(method, amount);
}
Важное замечание: Как указано в документации Oracle, “Имя может содержать пробелы внутри скобок, например, между аргументами метода.” Это означает, что при необходимости для читаемости можно включать пробелы в списки параметров.
Лучшие практики и распространенные ошибки
Правильное использование
// Правильно - метод в том же классе
/** Вызывает {@link #initialize()} для настройки компонента */
// Правильно - метод в другом классе
/** Использует {@link java.util.Collections#emptyList()} для пустой коллекции */
// Правильно - цепочки методов
/** Эквивалентно {@link #getDatabase()}.{@link Connection#close()} */
Распространенные ошибки, которых следует избегать
// Неправильно - отсутствуют скобки
/** Вызывает {@link #initialize} вместо {@link #initialize()} */
// Неправильно - лишние пробелы после открывающей скобки
/** Вызывает {@link # initialize()} (пробел после { предотвращает парсинг) */
// Неправильно - смешивание с обычным текстом
/** Вызывает {@link #getFoo()}.getBar() вместо {@link #getFoo()}.{@link #getBar()} */
Как показывают результаты исследований, “Следует отметить, что не должно быть пробелов между открывающей фигурной скобкой { и @link. Инструмент Javadoc не сгенерирует ссылку правильно, если между ними есть пробел.” источник
Продвинутые примеры
Статические методы
/**
* Преобразует значение в строковое представление
* Использует {@link Integer#toString(int)} для преобразования
* @param значение целого числа для преобразования
* @return строковое представление
*/
public String convertToString(int value) {
return Integer.toString(value);
}
Ссылки на конструкторы
/**
* Создает новый экземпляр с конфигурацией по умолчанию
* Создает экземпляр с помощью {@link Configuration#Configuration()}
* @return новый экземпляр конфигурации
*/
public Configuration createDefaultConfiguration() {
return new Configuration();
}
Обобщенные методы
/**
* Обрабатывает коллекцию элементов
* Использует {@link java.util.stream.Stream#map(Function)} для преобразования
* @param коллекция для обработки
* @return преобразованная коллекция
*/
public List<String> processItems(List<Item> items) {
return items.stream().map(Item::getName).collect(Collectors.toList());
}
Внешние ссылки
/**
* Получает информацию о текущей версии
* См. {@link https://example.com/api/v1/docs} для документации API
* @return строка версии
*/
public String getVersion() {
return "1.0.0";
}
Заключение
Правильное использование тега @link в Javadoc требует понимания этих ключевых моментов:
- Базовый синтаксис: Используйте
{@link className#methodName()}для ссылок на методы - Сокращения для методов в том же классе: Используйте
#methodName()для методов в текущем классе - Цепочки методов: Создавайте отдельные ссылки для каждого метода с отдельными тегами @link
- Указание параметров: Включайте типы параметров для различения перегруженных методов
- Точность синтаксиса: Нет пробелов между
{и@link, и всегда включайте скобки для методов
Следование этим практикам создаст чистую, удобную для навигации документацию, которая поможет разработчикам понимать связи в коде и быстро переходить к ссылаемым методам. Тег @link является одним из самых мощных инструментов в Javadoc для создания взаимосвязанной документации, которая повышает поддерживаемость кода и улучшает опыт разработчика.