Javadoc允许哪些HTML属性？如何在注释中使用lang属性？

问题核心 #

在Javadoc文档注释的HTML元素上使用lang属性时，会被Doclint拦截；不想全局关闭HTML错误检查，希望合规实现多语言标注，当前用自定义taglet转译的方案不够理想，同时找不到Javadoc允许的HTML属性完整列表。

可行解决方案 #

1. 合规绕过Doclint的写法（推荐） #

Javadoc的Doclint对HTML属性限制严格，lang这类语义化全局属性默认不在允许范围内，但可以通过以下方式实现类似需求：

• 利用Javadoc允许的class属性标记语言，后续配合生成文档的自定义CSS补充语义或样式，示例：

  <i class="lang-de">Hallo Welt</i>
  

• 若仅需展示标注，也可以用文本说明配合{@code}标签，比如：{@code [de] Hallo Welt}，虽然不够语义化，但完全符合Doclint规则。

2. 局部放宽Doclint检查 #

如果必须使用lang属性，无需全局关闭错误检查，可在注释中局部禁用再恢复：

/**
 * 示例方法说明
 * <!-- html-check-disable -->
 * <i lang="de">Hallo Welt</i>
 * <!-- html-check-enable -->
 */

这种方式只会跳过指定区域的HTML检查，不影响其他注释的合规性。

3. Javadoc默认允许的HTML属性列表 #

Javadoc仅支持用于基础文档格式化的HTML属性，不同JDK版本略有差异，常见允许的属性包括：

• 链接标签：<a>的href属性
• 列表标签：<ol>/<ul>的type属性
• 表格标签：<table>/<td>/<th>的border、cellpadding、cellspacing、width、align属性
• 文本块标签：<p>/<h1>-<h6>的align属性
• 通用属性：部分版本支持class、id属性

语义化全局属性（如lang、aria-*等）默认都不在允许范围内。

4. 自定义taglet方案优化 #

如果坚持保留lang属性的语义化标记，可以优化现有taglet：

• 让taglet输出带class属性的标签，再通过生成文档后的脚本，批量为对应class的元素添加lang属性，既符合Doclint规则，又能保留语义化效果。

内容的提问来源于stack exchange，提问作者Bolpat