1. Введение
В этом руководстве мы обсудим, как ссылаться на методы Java в комментариях Javadoc . Кроме того, мы рассмотрим, как ссылаться на методы в разных классах и пакетах.
2. Тег @link
Javadoc предоставляет встроенный тег @link для ссылки на элементы в классах Java . Мы можем думать о теге @link как о теге привязки в HTML, который используется для связывания одной страницы с другой через гиперссылки.
Давайте посмотрим на синтаксис использования тега @link для ссылки на методы в комментарии Javadoc:
{@link path_to_member label}
Подобно тегу привязки, path_to_member является пунктом назначения, а метка — отображаемым текстом.
Метка необязательна, но для ссылки на метод требуется path_to_member . Однако рекомендуется всегда использовать имя метки, чтобы избежать сложных ссылок. Синтаксис path_to_member различается в зависимости от того, находится ли метод, на который мы ссылаемся, в том же классе или нет.
Следует отметить, что между открывающей фигурной скобкой { и @link не должно быть пробелов . Инструмент Javadoc не будет правильно генерировать ссылку, если между ними есть пробел. Однако между path_to_member , label и закрывающей фигурной скобкой нет ограничений по пробелам.
3. Ссылка на метод в том же классе
Самый простой способ сослаться на метод — из того же класса:
{@link #methodName() LabelName}
Допустим, мы документируем метод и хотим сослаться на другой метод из того же класса:
/**
* Also, check the {@link #move() Move} method for more movement details.
*/
public void walk() {
}
public void move() {
}
В этом случае метод walk() ссылается на метод экземпляра move() в том же классе.
Если у метода, на который ссылаются, есть аргументы, мы должны соответствующим образом указывать тип его аргументов всякий раз, когда мы хотим сослаться на перегруженный или параметризованный метод .
Рассмотрим следующий пример, относящийся к перегруженному методу:
/**
* Check this {@link #move(String) Move} method for direction-oriented movement.
*/
public void move() {
}
public void move(String direction) {
}
Метод move() относится к перегруженному методу, который принимает один аргумент типа String .
4. Ссылка на метод в другом классе
Чтобы сослаться на метод в другом классе, мы будем использовать имя класса, за которым следует хэштег, а затем имя метода:
{@link ClassName#methodName() LabelName}
Синтаксис подобен ссылке на метод в том же классе, кроме упоминания имени класса перед символом # .
Теперь давайте рассмотрим пример ссылки на метод в другом классе:
/**
* Additionally, check this {@link Animal#run(String) Run} method for direction based run.
*/
public void run() {
}
Упомянутый метод находится в классе Animal , который находится в том же пакете :
public void run(String direction) {
}
Если мы хотим сослаться на метод, который находится в другом пакете, у нас есть 2 варианта. Один из способов — напрямую указать пакет вместе с именем класса :
/**
* Also consider checking {@link com.foreach.sealed.classes.Vehicle#Vehicle() Vehicle}
* constructor to initialize vehicle object.
*/
public void goToWork() {
}
В данном случае класс Vehicle был упомянут с полным именем пакета для ссылки на метод Vehicle() .
Кроме того, мы можем импортировать пакет и указать только имя класса :
import com.foreach.sealed.records.Car;
/**
* Have a look at {@link Car#getNumberOfSeats() SeatsAvailability}
* method for checking the available seats needed for driving.
*/
public void drive() {
}
Здесь был импортирован класс Car , который находится в другом пакете. Таким образом, @link должен включать только имя класса и метод.
Мы можем выбрать любой из двух способов ссылки на методы в другом пакете. Если есть одноразовое использование пакета, то мы можем пойти по первому пути, в противном случае мы должны выбрать второй путь, если есть несколько зависимостей.
5. Тег @linkplain
Мы видели тег @link Javadoc для ссылки на методы в комментариях. Javadoc предоставляет еще один тег с именем @linkplain для ссылки на методы в комментариях, который аналогичен тегу @link . Основное отличие состоит в том, что при создании документации @link создает значение метки в моноширинном формате текста, а @linkplain создает его в стандартном формате, таком как обычный текст .
6. Заключение
В этой статье мы обсудили, как ссылаться на методы в комментариях Javadoc, а также рассмотрели ссылки на методы в других классах и пакетах. Наконец, мы рассмотрели разницу между тегами @link и @linkplain .
Как всегда, примеры кода из этой статьи можно найти на GitHub .