Javadoc中允许的HTML标记

时间:2013-05-10 11:29:51

标签: html javadoc checkstyle

Checkstyle规则JavadocStyle不允许使用标记<u>。根据文档,在Sun提供的DocCheck doclet检查后,检查结果已经过模式化。不幸的是,我没有在任何地方找到DocCheck。我也没有在Javadoc中找到任何关于允许的HTML标记的官方文档。有没有?

2 个答案:

答案 0 :(得分:27)

从Java 8开始,Javadoc只允许HTML标记的一个子集。

Javadoc的doclint组件强制执行此限制。 您可以通过将-Xdoclint:none传递给javadoc来禁用所有doclint警告, 虽然您应该考虑修复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

答案 1 :(得分:14)

在Javadoc评论中使用HTML没有实际限制。 Javadoc documentation州:

  

评论是用HTML编写的 - 文本必须用HTML编写,因为它们应该使用HTML实体并且可以使用HTML标记。 您可以使用浏览器支持的任何版本的HTML; 我们编写了标准doclet,以便在其他地方(文档注释之外)生成符合HTML 3.2的代码,并包含级联样式表和框架。 (我们在每个生成的文件前加上&#34; HTML 4.0&#34;因为框架集。)

允许的HTML标记列表在JavadocStyle Checkstyle检查中进行了硬编码(通过查看Checkstyle 5.6源代码进行验证)。因此,如果您想要检查其他好的属性,则必须使用受限制的HTML标记集。下划线问题的一种解决方法是使用CSS(允许),如下所示:

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