Использование символов < и > в javadoc: обход форматирования
Быстрый ответ
Для того чтобы правильно вставить символы <
и >
, используйте HTML-мнемоники <
и >
в Javadoc.
Пример использования:
/**
* Может, это не приложение для знакомств, но время от времени нам все же приходится проводить сравнения:
* {@code a < b} или {@code a > b}?
*
* @param a первое числовое значение для сравнения
* @param b второе числовое значение для сравнения
* @return true, если {@code a} меньше {@code b}
*/
public boolean isLessThan(int a, int b) {
return a < b; // Четкое и понятное сравнение
}
Что скрыто за кодом: зачем нужно экранирование
Символы <
и >
не рекомендуется использовать напрямую в Javadoc, поскольку они могут быть восприняты как HTML-теги. Чтобы избежать путаницы используются HTML-мнемоники <
и >
. Это позволяет безопасно добавлять угловые скобки в комментариях Javadoc.
Специфика Javadoc: {@code} или {@literal}
Используйте {@literal ...}
, чтобы представить обычный текс или символы, не являющиеся частью кода. А для вывода фрагментов кода выбирайте {@code ...}
. Например:
/**
* Сказав "{@literal A<B>C}", мы просто передаем информацию.
* Но воспользовавшись "{@code A<B>C}", мы столкнемся с недопониманием, так как в коде так не принято.
*/
Многострочный код в Javadoc: сочетание <pre>{@code}</pre>
Для демонстрации многострочного кода используйте комбинацию тега <pre>
и {@code}
. Тег <pre>
сохраняет форматирование, а {@code}
позволяет элегантно использовать символы <
и >
внутри кода:
/**
* Рассмотрим диалоги на примере программы:
* <pre>{@code
* if (cats < dogs) {
* // Увы, коты, но собаки управляют миром.
* } else if (cats > dogs) {
* // Коты правят миром! Где такое можно наблюдать?
* }
*}</pre>
*/
Когда следует использовать {@code} или {@literal}
- Применяйте
{@code ...}
, если в Javadoc вставляются фрагменты XML или какого-нибудь другого кода. - Используйте
{@literal ...}
, если текст содержит символы<
и>
, или если они должны отображаться прямо в документации.
Возможные проблемы и решения
- Неэкранированные символы
<
и>
, могут вызвать ошибки компиляции и нарушить структуру Javadoc. - Старые версии инструмента Javadoc могут не поддерживать
{@literal ...}
и{@code ...}
. - Всегда стоит обращаться к официальной документации Java для информации о современных возможностях и совместимости.
Визуализация
Представьте символы <
и >
, как участников маскарада, желающих сохранить инкогнито:
- `<` замещает скромного `<`.
- `>` заменяет загадочного `>`.
Эти коды позволяют угловым скобкам быть собой, не вызывая путаницы:
/**
* Сравниваем в маскарадных костюмах:
* – Малыш Йода слабее: Малыш Йода < Йода
* – Дарт Вейдер страшнее: Дарт Вейдер > Штурмовик
*/
Таким образом, <
и >
могут занимать своё место в Javadoc без каких-либо изменений. 🌟