Экранирование символа @ в javadoc: правильный способ

Быстрый ответ

Чтобы символ @ не интерпретировался как тег Javadoc, используйте HTML-сущность @:

/**
 * Наш контактный email: admin@domain.com.
 */

Таким способом емэйл "admin@domain.com" будет корректно отображаться в HTML Javadoc. Для улучшения читаемости можно применять тег {@literal}:

/**
 * Пример использования {@literal @} в емэйлах и в Javadoc.
 */

Изучаем артистизм экранирования символов

Знакомство с тегом {@literal}

Тег {@literal} — это стандартный способ экранирования символов в Javadoc, способствующий повышению читаемости и точности:

/**
 * Пример внедрения {@literal @} в комментарии Javadoc.
 */

Этот подход позволяет вам избегать использования кодов символов и четко показывать, что вы хотите отобразить текст буквально.

Подробнее об этом расскажет наш спикер на видео

Обращаемся с фрагментами кода и вложенными тегами

Тег {@literal} может использоваться совместно с {@code} и в обратном порядке – это особенно релевантно для блоков <pre>, когда в Javadoc вставляются отрывки кода:

/**
 * Рассмотрим следующий пример:
 * <pre>
 * {@code
 * // Email-адрес с символом {@literal @}?
 * String email = "admin{@literal @}domain.com";
 * }
 * </pre>
 */

Особенности различных версий JDK

В Javadoc начиная с версии 15.0.2 не требуется экранировать символ @ внутри {@code}. Однако в более ранних версиях это остаётся актуальным. Следите за обновлениями баг-трекера JDK JDK-8130754 для получения наиболее свежих исправлений.

Визуализация

В современных диалогах знак @ часто используется в емэйлах и социальных сетях, однако в JavaDoc он требует специфического подхода:

Таким способом, мы «упаковываем» его в безопасный HTML-код (`@`), чтобы JavaDoc не воспринял его как тег:

До: 🙈 -> JavaDoc воспринимает знак @ как ТЕГ! После: 🛡️@🛡️ -> JavaDoc трактует символ @ как надлежит, предупреждение о ТЕГе не следует.

Следовательно, нашему любезному @ требуется «безопасный кокон» (@), чтобы JavaDoc воспринимал его как надлежит.

Технические подробности экранирования символов

Использование восьмеричного и десятичного представлений

В качестве альтернативы {@literal} служат восьмеричное (\100) и десятичное (@) HTML-представления для @:

/**
 * Отмечаем:
 * Десятичное: admin@domain.com
 * Восьмеричное: admin\100domain.com (не путать с шифром агента 007)
 */

Сохраняем баланс между читаемостью и совместимостью

Применяйте {@literal} чтобы документация была чистой и понятной, не забывая о возможных различиях в совместимости с инструментами Javadoc в зависимости от их версии и настроек. Обязательно проводите необходимые тесты.

Вникаем в официальные рекомендации

Чтобы всегда быть проинформированным о лучших методах работы со спецсимволами, всегда имейте под рукой официальное руководство Javadoc.

Полезные материалы

1. javadoc — основное руководство от компании Oracle по использованию Javadoc.
2. Как создавать документационные комментарии для Javadoc — подробное руководство от Oracle по написанию документации для Javadoc.
3. StringEscapeUtils (API Apache Commons Lang 3.11) — Инструмент Apache Commons для экранирования строк, который подойдёт для различных задач.
4. Как правильно экранировать текст для XML в Java? – Stack Overflow — Для анализа мнений сообщества стоит ознакомиться с обсуждением на Stack Overflow.
5. Руководство по оформлению фрагментов кода в Javadoc – DZone — Бесценные советы по оформлению кода и экранированию в Javadoc.