The Checkstyle rule JavadocStyle does not allow the tag <u>
. According to the docs, the checks were patterned after the checks made by the DocCheck doclet available from Sun. Unfortunately, I have not found DocCheck anywhere. Neither have I found any official documentation about allowed HTML tags in Javadoc. Is there any?
2 Answers
Javadoc permits only a subset of HTML tags.
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 the JDK's file .../doclint/HtmlTag.java
.
Java 17
A
ABBR
ACRONYM
ADDRESS
ARTICLE
ASIDE
B
BDI
BIG
BLOCKQUOTE
BODY
BR
CAPTION
CENTER
CITE
CODE
COL
DD
DEL
DFN
DIV
DT
EM
FONT
FIGURE
FIGCAPTION
FRAME
FRAMESET
H1
H2
H3
H4
H5
H6
HEAD
HR
HTML
I
IFRAME
IMG
INS
KBD
LI
LINK
MAIN
MARK
META
NAV
NOFRAMES
NOSCRIPT
P
Q
S
SAMP
SCRIPT
SECTION
SMALL
SPAN
STRIKE
STRONG
STYLE
SUB
SUP
TD
TEMPLATE
TH
TIME
TITLE
TT
U
UL
WBR
VAR
Java 8
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
Java 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.
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
-
1How do we include a script tag in javadoc? I need to load a javascript file when the javadocs load (for code syntax highlighting). Any idea how to accomplish that? Feb 18, 2019 at 1:26
-
1@AlexanderMills it sounds like you should not use a
<script>
tag to accomplish syntax highlighting, but use a [Doclet](docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/overview.html), Java code that hits the Java Doclet API "to specify the content and format of the output of the Javadoc tool". Apr 4, 2019 at 15:42 -
I wonder if there are security issues in being able to execute scripts in JavaDoc. But probably others have wondered that before and came to a negative conclusion, that's usually the case for every tiny detail in Java. May 11, 2020 at 15:37
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>
-
3FYI, the
<u>
element was explicitly added to the hardcoded list of tags in Checkstyle 5.8. The list can still not be modified, but this particular problem is solved.– barfuinFeb 12, 2015 at 17:04 -
for me I tried
<del>
but did not work,<s>
did the trick, thanks to your comment Jan 9, 2022 at 15:02