Перейти к основному содержимому

Ссылка на метод в Javadoc комментариях

· 4 мин. чтения

1. Введение

В этом руководстве мы обсудим, как ссылаться на методы Java в комментариях Javadoc . Кроме того, мы рассмотрим, как ссылаться на методы в разных классах и пакетах.

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 .