Разрешенные теги HTML в Javadoc

Ответ 1

Javadoc разрешает только подмножество HTML-тегов, начиная с Java 8.

Компонент Javadoc doclint применяет это ограничение. Вы можете отключить все предупреждения doclint, передав -Xdoclint:none в javadoc, хотя вам стоит подумать об исправлении ваших комментариев Javadoc, потому что иначе созданная документация HTML API может выглядеть плохо или может опустить контент. (Обычно я использую -Xdoclint:all,-missing, чтобы получать предупреждения обо всем, кроме тегов Javadoc @.)

Я не нашел публичную документацию о тегах, которые разрешает doclint, но вот список ее разрешенных HTML-тегов, которые я почерпнул из файла Java 8 langtools/src/share/classes/com/sun/tools/doclint/HtmlTag.java.

A
B
BIG
BLOCKQUOTE
BODY
BR
CAPTION
CENTER
CITE
CODE
DD
DFN
DIV
DL
DT
EM
FONT
FRAME
FRAMESET
H1
H2
H3
H4
H5
H6
HEAD
HR
HTML
I
IMG
LI
LINK
MENU
META
NOFRAMES
NOSCRIPT
OL
P
PRE
SCRIPT
SMALL
SPAN
STRONG
SUB
SUP
TABLE
TBODY
TD
TFOOT
TH
THEAD
TITLE
TR
TT
U
UL
VAR

Обновление для JDK 9

JDK 9 допускает другой набор тегов, чем JDK 8. Вот список тегов для обоих JDK, с примечаниями о тех, которые разрешены только одним из JDK. Опять же, данные поступают из файла HTMLTag.java.

A
BIG       // JDK 8 only
B         // JDK 8 only
BLOCKQUOTE
BODY
BR
CAPTION
CENTER
CITE      // JDK 8 only
CODE
DD
DFN       // JDK 8 only
DIR       // JDK 9 only
DIV
DL
DT
EM
FONT
FOOTER    // JDK 9 only
FRAME     // JDK 8 only
FRAMESET  // JDK 8 only
H1
H2
H3
H4
H5
H6
HEAD
HEADER     // JDK 9 only
HR
HTML
I
IFRAME     // JDK 9 only
IMG
INPUT      // JDK 9 only
LI
LINK
LISTING    // JDK 9 only
MAIN       // JDK 9 only
MENU
META
NAV        // JDK 9 only
NOFRAMES   // JDK 8 only
NOSCRIPT
OL
P
PRE
SCRIPT
SECTION     // JDK 9 only
SMALL
SPAN
STRONG
SUB
SUP         // JDK 8 only
TABLE
TBODY
TD
TFOOT       // JDK 8 only
TH
THEAD       // JDK 8 only
TITLE
TR
TT
U           // JDK 8 only
UL
VAR         // JDK 8 only

Ответ 2

Нет никаких реальных ограничений на использование HTML в комментариях Javadoc. Документация Javadoc гласит:

Комментарии написаны в HTML - текст должен быть написан в HTML, поскольку они должны использовать HTML-сущности и использовать теги HTML. Вы можете использовать любую версию HTML, поддерживаемую вашим браузером; мы написали стандартный doclet для создания HTML-совместимого кода в другом месте (за пределами комментариев документации) с включением каскадных таблиц стилей и фреймов. (Мы предваряем каждый сгенерированный файл "HTML 4.0" из-за наборов кадров.)

Список допустимых тегов HTML жестко закодирован в тесте JavadocStyle Checkstyle (проверен, просмотрев источники Checkstyle 5.6). Поэтому, если вы хотите сохранить проверку на наличие других хороших свойств, вам придется жить с ограниченным набором тегов HTML. Одним из способов решения проблемы подчеркивания является использование CSS (что разрешено) следующим образом:

<span style="text-decoration:underline;">underlined text</span>