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

Ссылка на внешний URL в Javadoc

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

1. Введение​

При написании нашего кода мы можем ссылаться на статьи в Интернете, такие как вики-страницы, руководства или официальную документацию библиотеки. Было бы неплохо добавить ссылки на такие справочные статьи в Javadoc.

В этом руководстве мы узнаем, как ссылаться на внешний URL-адрес в Javadoc.

2. Создание встроенной ссылки​

Java не предлагает никаких специальных инструментов для внешних ссылок, но мы можем просто использовать стандартный HTML. Для создания встроенной ссылки используется следующий синтаксис:

/**
 * Some text <a href="URL#value">label</a> 
 */

Здесь значение URL# может быть относительным или абсолютным URL.

Рассмотрим пример:

/** 
 * Refer to <a href="http://www.foreach.com">ForEach</a> 
 */

Это будет отображаться как:

Обратитесь к ForEach

3. Создание встроенной ссылки с заголовком​

Другой способ — создать заголовок, содержащий ссылку. Для этого используется тег @see следующим образом:

/**
 * @see <a href="URL#value">label</a>
 */

Рассмотрим следующий пример:

/**
 * @see <a href="http://www.foreach.com">ForEach</a> 
 */

Это создаст заголовок «См. также», содержащий ссылку:

См. также:

ForEach

4. Создание ссылки на Javadoc другого класса​

Тег @link специально используется для ссылки на Javadoc других классов и методов. Это встроенный тег, который преобразуется в гиперссылку HTML, указывающую на документацию данного класса или ссылки на метод:

{@link <ссылка на класс или метод>}

Предположим, у нас есть класс DemoOne , содержащий демо -метод :

/** 
 * Javadoc
 */
class DemoOne {
  
  /**
   * Javadoc
  */
  void demo() {
    //some code
  }
}

Теперь мы можем ссылаться на Javadoc вышеуказанного класса и метода из другого класса следующими способами:

/** 
 * See also {@link org.demo.DemoOne}
 */
/**
 * See also {@link org.demo.DemoOne#demo()}
 */

Этот тег можно использовать везде, где можно написать комментарий, а @see создает свой собственный раздел.

Подводя итог, @link предпочтительнее, когда мы используем имя класса или метода в описании. С другой стороны, @see используется, когда соответствующая ссылка не упоминается в описании или как замена нескольких ссылок на одну и ту же ссылку.

5. Вывод​

В этой статье мы узнали о способах создания внешней ссылки в Javadoc. Мы также рассмотрели разницу между тегами @see и @link .