JavaDoc预格式化文本块中能否使用<sub>和<sup>标签？

你碰到的这个情况是JDK11 JavaDoc的一个明确限制：虽然JDK11本身支持<sub>和<sup>标签，但它们不能嵌套在<pre>块内——预格式化块的HTML解析规则会禁止这类行内标签，这也是maven-javadoc-plugin抛出错误的核心原因。

下面是几个合规的解决方案，亲测在JDK11+maven-javadoc-plugin环境下有效：

方案1：用<code>标签替代<pre> #

<code>是行内代码标签，JavaDoc允许在其中嵌套<sub>/<sup>，既能保留代码的等宽字体样式，又能正确渲染下标/上标。把你的示例改成这样：

/**
 * Format: 8 octets (<code>U<sub>8</sub> [r<sub>4</sub>U<sub>4</sub>] [r<sub>3</sub>U<sub>5</sub>] [r<sub>3</sub>U<sub>5</sub>] [r<sub>2</sub>U<sub>6</sub>] [r<sub>2</sub>U<sub>6</sub>] B<sub>16</sub></code>)
 */

修改后，maven-javadoc-plugin不会再触发错误，生成的JavaDoc也能正确显示下标效果。

方案2：拆分{@code}与<sub>/<sup> #

如果你更习惯使用JavaDoc原生的{@code}标签，可以把需要下标/上标的部分拆分开，分别用{@code}包裹代码内容，<sub>/<sup>单独处理：

/**
 * Format: 8 octets ({@code U}<sub>8</sub> {@code [r}<sub>4</sub>{@code U}<sub>4</sub>{@code ]} {@code [r}<sub>3</sub>{@code U}<sub>5</sub>{@code ]} {@code [r}<sub>3</sub>{@code U}<sub>5</sub>{@code ]} {@code [r}<sub>2</sub>{@code U}<sub>6</sub>{@code ]} {@code [r}<sub>2</sub>{@code U}<sub>6</sub>{@code ]} {@code B}<sub>16</sub>)
 */

这种写法虽然稍显繁琐，但完全符合JavaDoc的规范，不会产生任何警告或错误，渲染效果也和预期一致。

方案3：放宽插件检查（不推荐） #

如果你实在需要保留<pre>块，又想暂时绕过错误，可以调整maven-javadoc-plugin的配置，关闭相关的文档检查：
在pom.xml的插件配置中添加：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <!-- 精准忽略HTML标签相关错误，不关闭其他检查 -->
    <additionalparam>-Xdoclint:all,-html</additionalparam>
  </configuration>
</plugin>

不过这个方案本质是忽略问题而非解决，可能会掩盖其他潜在的JavaDoc合规问题，所以优先推荐前两种方案。

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