1. Обзор
На языке Java мы можем генерировать документацию в формате HTML из исходного кода Java с помощью Javadoc . В этом руководстве мы узнаем о различных способах добавления ссылки на параметры метода в Javadoc.
2. Различные способы добавления ссылки на параметр метода
В этом разделе мы поговорим о добавлении ссылки на параметр метода в Javadoc. Мы увидим использование встроенного тега {@code} и тега стиля HTML </co de> в Javadoc.
Далее мы увидим, как теги {@code} и <code> позаботятся о нескольких особых случаях:
- отображение специальных символов '<', '>' и '@'
- отступы и разрывы строк
- обработка экранирования кодов HTML — например, <, который переводится как символ '<'
2.1. Тег {@code }
{@code text} — это встроенный тег, который был включен в JDK 1.5 .
Тег {@code} форматирует обычный текст шрифтом кода. {@code abc} эквивалентен <code>{@literal abc}</code> .
Нам не нужно вручную экранировать какой-либо специальный символ, используемый внутри тега {@code} .
Когда мы используем тег {@code} , он:
- отображает '<' и '>' правильно
- отображает '@' правильно
- не нужно экранировать специальные символы с помощью числовых кодов HTML
- более читабелен и лаконичен
Давайте создадим простой метод в классе и добавим немного Javadoc, используя тег {@code} :
/**
* This method takes a {@code String}
* and searches in the given list {@code List<String>}
*
* @param name
* Name of the person
* @param avengers
* list of Avengers names
* @return true if found, false otherwise
*/
public Boolean isAvenger(String name, List<String> avengers) {
return avengers.contains(name);
}
Здесь мы видим, что нам не нужно экранировать специальные символы '<' и '>'.
Сгенерированный Javadoc будет отображать вывод HTML как:
**
**
Точно так же мы можем видеть, что нам не нужно экранировать символ «@»:
/**
* This is sample for showing @ use without any manual escape.
* {@code @AnyAnnotaion}
*
*/
public void javadocTest() {
}
Это будет отображаться в HTML Javadoc как:
В случае многострочного фрагмента кода в Javadoc {@code} не будет поддерживать отступ и разрыв строки. Чтобы преодолеть это, мы можем использовать HTML-тег <pre> вместе с {@code} . Однако в этом случае нам нужно экранировать символ «@».
2.2. Тег <code >
<code> — это тег стиля HTML, поддерживаемый Javadoc.
Когда мы используем тег <code> , он:
- неправильно отображает '<' и '>'
- требует экранирования специальных символов с помощью числовых кодов HTML
- не так читабельно
Давайте снова рассмотрим тот же пример. Мы видим, что в сгенерированном Javadoc HTML отсутствует параметризованный тип <String> после списка в нашем абзаце :
/**
* This method takes a <code>String</code>
* and searches in the given <code>List<String></code>
*
* @param name
* Name of the person
* @param avengers
* list of Avengers names
* @return true if found, false otherwise
*/
public Boolean isAvenger(String name, List<String> avengers) {
return avengers.contains(name);
}
Здесь, если мы экранируем специальные символы '<' и '>' в нашем комментарии к методу, тогда он отобразит правильный <String> в Javadoc:
/**
* This method takes a <code>String</code>
* and searches in the given <code>List<String></code>
*
* @param name
* Name of the person
* @param avengers
* list of Avengers names
* @return true if found, false otherwise
*/
public Boolean isAvenger(String name, List<String> avengers) {
return avengers.contains(name);
}
3. Заключение
В этом руководстве мы впервые рассказали о том, как использовать {@code} и <code> для ссылки на параметры метода в Javadoc. Затем мы описали обработку спецсимволов этими тегами. В заключение, теперь мы понимаем, как добавлять ссылки на параметры метода в Javadoc, и мы видим, что {@code} лучше, чем <code> в любой день.