RU
EN
ES
ZH
FR
DE
PT
AR
HI
debug_master24
·
Как правильно ссылаться на методы в Javadoc и что такое {@link}?
Правильный синтаксис ссылок на методы в Javadoc
В Javadoc для создания ссылок на методы, поля или классы используется специальный тег {@link} или {@linkplain}. Основная проблема в вашем коде — вы используете просто #add без обрамления в тег. Правильный синтаксис: {@link #add}. Давайте разберём все варианты подробно.
1. Ссылка на метод в том же классе (без параметров)
Если метод не перегружен и находится в том же классе, достаточно написать:
/**
* Выводит сумму двух чисел, используя метод {@link #add}.
*/
public void sumAndPrint(int x, int y) { ... }Javadoc автоматически найдёт метод add в текущем классе. В сгенерированной HTML-документации появится кликабельная ссылка.
2. Ссылка на метод с параметрами (для перегруженных методов)
Если метод перегружен (например, есть add(int, int) и add(double, double)), нужно указать типы параметров для однозначной идентификации:
/**
* Выводит сумму целых чисел, используя {@link #add(int, int)}.
* Для вещественных чисел есть {@link #add(double, double)}.
*/
public void sumAndPrint(int x, int y) { ... }Пробелы между типами параметров необязательны, но их можно ставить для читаемости.
3. Ссылка на метод из другого класса
Если метод находится в другом классе, укажите полное имя класса или пакет:
import com.example.Calculator;
/**
* Использует {@link Calculator#add(int, int)} для вычислений.
*/
public class MathService { ... }Если класс находится в другом пакете, укажите полный путь:
/**
* Ссылка на метод из другого пакета: {@link com.example.utils.Calculator#add(int, int)}.
*/4. Ссылка на метод с возвращаемым типом или модификатором
Иногда нужно сослаться на метод, указав его полную сигнатуру. Это полезно для документации API:
/**
* Этот метод переопределяет {@code public int add(int a, int b)} из родительского класса.
* См. {@link #add(int, int)}.
*/5. Альтернативные теги: {@linkplain} и {@code}
- {@linkplain} — то же самое, что {@link}, но текст ссылки отображается обычным шрифтом (не моноширинным).
- {@code} — просто форматирует текст как код, без создания ссылки. Полезно для упоминания имени метода без гиперссылки.
Пример:
/**
* Используйте {@code add} для сложения, подробнее см. {@link #add(int, int)}.
*/6. Ссылка на метод в этом же файле (без имени класса)
Если вы находитесь в том же классе, можно опустить имя класса:
/**
* Вызывает {@link #add(int, int)}.
*/Но для лучшей читаемости и избежания путаницы рекомендуется всегда указывать имя класса, даже если он текущий.
7. Полезные советы
- Используйте IntelliJ IDEA или Eclipse — они подсвечивают корректность ссылок в Javadoc и предлагают автодополнение.
- После написания Javadoc обязательно сгенерируйте документацию командой
javadocи проверьте, что ссылки работают. - Для ссылок на методы без параметров можно не указывать пустые скобки, но со скобками читается понятнее:
{@link #add()}.
Исправленный код вашего примера:
/**
* Выводит сумму двух чисел, используя метод {@link #add(int, int)}.
* @param x первое число
* @param y второе число
*/
public void sumAndPrint(int x, int y) {
System.out.println(add(x, y));
}Теперь при генерации Javadoc слово "add" станет кликабельной ссылкой на метод add(int, int).
Дополнительный способ: ссылка на метод через {@link #methodName()}
Если вы хотите сослаться на метод, но не хотите указывать параметры (например, когда перегрузки нет), можно использовать синтаксис с пустыми скобками:
/**
* См. также {@link #add()}.
*/Однако этот способ работает только если метод не перегружен. Если есть несколько методов с одинаковым именем, Javadoc выдаст предупреждение и ссылка может не сработать. В таком случае лучше всегда указывать типы параметров.
Ссылка на метод в другом классе через импорт
Если класс импортирован, можно использовать сокращённую форму:
import com.example.Calculator;
/**
* Использует {@link Calculator#add(int, int)}.
*/Если класс не импортирован, но находится в том же пакете, тоже можно использовать короткое имя. В противном случае — только полное.
Автоматическая генерация ссылок в IntelliJ IDEA
В IntelliJ IDEA можно быстро вставить ссылку на метод: начните печатать {@link , затем нажмите Ctrl+Space — среда предложит список доступных методов и классов. Это очень удобно и исключает ошибки. Аналогично работает в Eclipse с Ctrl+Space.
Проверка сгенерированной документации
После написания Javadoc выполните команду в терминале:
javadoc -d doc MyClass.javaОткройте файл doc/index.html в браузере и проверьте, что ссылки активны. Если ссылка не работает, Javadoc выведет предупреждение при генерации — обращайте на них внимание.
