Как добавить внешние ссылки в Javadoc

Чтобы корректно ссылаться на внешние URL в Javadoc, следует использовать HTML‑теги <a href="URL">, а не тег @link, который предназначен исключительно для ссылок на внутренние классы и методы Java. Синтаксис /** See {@link http://google.com} */ не сработает, потому что @link ожидает ссылку на класс или метод, а не веб‑адрес.

Содержание

• Почему @link не работает для внешних URL
• Правильный синтаксис HTML‑тега <a>
• Практические примеры
• Альтернативные подходы
• Распространённые ошибки и устранение неполадок
• Лучшие практики

Почему @link не работает для внешних URL

Тег @link в Javadoc специально предназначен для создания гиперссылок на внутреннюю документацию Java — на классы, методы, поля или пакеты вашего проекта или внешних Java‑API. Согласно Baeldung, «Тег @link используется для ссылки на Javadoc других классов и методов».

При попытке использовать /** See {@link http://google.com} */, инструмент Javadoc рассматривает http://google.com как имя класса, а не как URL, и выводит обычный текст вместо кликабельной ссылки. Тег @link ожидает синтаксис Java, такой как package.Class#method, а не веб‑адреса.

Тег @link очень похож на @see – оба требуют одинаковые ссылки и принимают точно такой же синтаксис package.class#member и метку. Основное отличие в том, что {@link} генерирует встроенную ссылку, а не помещает ссылку в раздел «See Also». Stack Overflow

Правильный синтаксис HTML‑тега <a>

Правильный способ ссылаться на внешние URL в Javadoc – использовать HTML‑теги <a> внутри комментариев Javadoc. Синтаксис соответствует стандартному HTML:

/**
 * See <a href="https://google.com">Google</a> for more information.
 */

Ключевые моменты:

• Используйте <a href="полный-URL">текст ссылки</a>
• Всегда включайте протокол (http:// или https://)
• Текст ссылки становится кликабельным в сгенерированной документации
• Это работает как в контекстах inline, так и внутри тегов @see

Согласно electro4u.net, «Чтобы связать с внешним URL в javadoc, необходимо использовать HTML‑тег <a> в вашем комментарии».

Практические примеры

Ниже приведены несколько практических примеров правильного связывания с внешними URL:

Базовая ссылка на внешний URL

/**
 * For HTTP specifications, see 
 * <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">HTTP/1.1 documentation</a>.
 */
public static final String ACCEPT = "Accept";

Ссылка в теге @see

/**
 * @see <a href="https://json.org">JSON specification</a>
 * @see <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status">HTTP Status Codes</a>
 */
public void processResponse() {
    // method implementation
}

Несколько ссылок в одном комментарии

/**
 * This method uses external libraries:
 * <ul>
 *   <li><a href="https://guava.dev">Google Guava</a> for collections</li>
 *   <li><a href="https://logging.apache.org/log4j">Apache Log4j</a> for logging</li>
 *   <li><a href="https://junit.org">JUnit</a> for testing</li>
 * </ul>
 */
public void setupDependencies() {
    // implementation
}

Реальный пример из Java API

Исследование показало примеры из собственной документации Java:

/**
 * See <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">HTTP/1.1 documentation</a>.
 */
public static final String ACCEPT = "Accept";

Альтернативные подходы

Использование тега @see с HTML‑ссылками

Тег @see также может содержать HTML‑теги <a> и создаёт раздел «See Also» в сгенерированной документации:

/**
 * @see <a href="https://example.com">External Reference</a>
 * @see <a href="https://docs.oracle.com/javase/tutorial">Java Tutorial</a>
 */
public class Example {
}

Использование @see с простыми URL

Можно также использовать @see с простыми URL, но это приводит к отображению URL как есть, без форматирования:

/**
 * @see http://example.com
 * @see https://docs.oracle.com/javase/8/docs/api/
 */
public void referenceUrls() {
}

Согласно Baeldung, «@see используется, когда релевантная ссылка не упоминается в описании или как замена нескольким ссылкам на один и тот же ресурс».

Распространённые ошибки и устранение неполадок

Ошибка 1: Использование @link для внешних URL

// ❌ Неправильно – не создаст кликабельную ссылку
/** See {@link http://google.com} */

Ошибка 2: Отсутствие протокола

// ❌ Неправильно – отсутствует http:// или https://
/** See <a href="google.com">Google</a> */

Ошибка 3: Неправильный HTML‑синтаксис

// ❌ Неправильно – неверный HTML
/** See <a href="https://google.com">Google</a> */

Советы по устранению неполадок

1. Всегда включайте протокол – URL должны начинаться с http:// или https://
2. Используйте правильный HTML‑синтаксис – убедитесь, что теги корректно закрыты
3. Проверьте генерацию Javadoc – запустите команду javadoc, чтобы убедиться, что ссылки отображаются правильно
4. Проверьте специальные символы – экранируйте специальные HTML‑символы в URL при необходимости

Лучшие практики

1. Используйте описательный текст ссылки вместо сырого URL
2. Включайте полный URL в атрибут href
3. Открывайте ссылки в новой вкладке добавив target="_blank" для лучшего UX
4. Группируйте связанные ссылки в организованных списках
5. Соблюдайте единообразие в подходе к ссылкам по всему проекту

/**
 * For more information, visit:
 * <a href="https://docs.oracle.com/javase/tutorial" target="_blank">Java Tutorial</a>
 */

Согласно Stack Overflow, наиболее надёжный подход – «Использовать HTML‑тег <a> в комментарии» для внешних ссылок в Javadoc.

Заключение

Чтобы корректно ссылаться на внешние URL в документации Javadoc:

1. Используйте HTML‑теги <a href="URL">текст ссылки</a> вместо тегов @link
2. Всегда включайте протокол (http:// или https://) в ваших URL
3. Рассмотрите возможность использования тегов @see для создания разделов «See Also» с внешними ссылками
4. Проверьте ваши ссылки сгенерировав Javadoc, чтобы убедиться, что они работают
5. Следуйте лучшим практикам HTML для доступности и удобства пользователя

Главный вывод: @link предназначен для внутренней документации Java, а внешние URL требуют стандартного синтаксиса HTML‑тега <a> внутри комментариев Javadoc.

Источники

1. Linking to an External URL in Javadoc - Stack Overflow
2. Linking to an External URL in Javadoc | Baeldung
3. Linking to an External URL in Javadoc - electro4u.net
4. Javadoc coding rule of @link, @linkplain, @see - corochann.com
5. Javadoc: @see, @link, and @inheritDoc | Baeldung
6. The javadoc Command - Oracle Documentation
7. How to Write Doc Comments for the Javadoc Tool - Oracle