Allowed HTML tags in Javadoc

Question

The Checkstyle rule JavadocStyle does not allow the tag . According to the docs, the checks were patterned after the checks made by the DocCheck doclet

Answer 1

There are no real restrictions on the use of HTML in Javadoc comments. The Javadoc documentation states:

Comments are written in HTML - The text must be written in HTML, in that they should use HTML entities and can use HTML tags. You can use whichever version of HTML your browser supports; we have written the standard doclet to generate HTML 3.2-compliant code elsewhere (outside of the documentation comments) with the inclusion of cascading style sheets and frames. (We preface each generated file with "HTML 4.0" because of the frame sets.)

The list of allowed HTML tags is hardcoded in the JavadocStyle Checkstyle check (verified by looking at the Checkstyle 5.6 sources). So if you want to keep the check for its other good properties, you will have to live with the restricted set of HTML tags. One workaround for the underline problem is to use CSS (which is allowed) like this:

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

Answer 2

Javadoc permits only a subset of HTML tags, as of Java 8.

Javadoc's doclint component enforces this restriction. You can disable all doclint warnings by passing -Xdoclint:none to javadoc, though you should consider fixing your Javadoc comments because otherwise the generated HTML API documentation may look bad or may omit content. (I usually use -Xdoclint:all,-missing to get warnings about everything except missing Javadoc @ tags.)

I have not found public documentation of the tags that doclint permits, but here is a list of its allowed HTML tags, which I gleaned from Java 8's file 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

Update for JDK 9

JDK 9 permits a different set of tags than JDK 8 does. Here is a list of tags for both JDKs, with notes about those permitted by only one of the JDKs. Again, the data comes from the HTMLTag.java file.

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