JavaDoc不支持<font>标签问题求助（Java 16 + Gradle环境）

核心原因 #

JavaDoc默认采用的HTML版本（如HTML4）不兼容<font>标签，而IntelliJ的渲染引擎兼容旧标签语法，所以本地编辑器能正常显示，但执行gradle javadoc生成文档时会触发兼容性错误。

可行解决方案 #

方案1：替换<font>为标准HTML标签 #

直接用HTML5的<span>标签替代<font>，既符合规范也能被JavaDoc正确解析，同时不影响IntelliJ的样式渲染：

/**
 * Websocket to handle changes.<br>
 * <span style="color:red">A RED COMMENT </span><br>
 * <span style="color:orange">AN ORANGE COMMENT</span>
 **/

方案2：配置Gradle忽略标签错误并启用HTML5 #

如果不想修改代码注释，可在build.gradle中配置JavaDoc任务，开启HTML5支持并关闭标签兼容性检查：

tasks.withType(Javadoc) {
    options {
        htmlVersion = '5'
        // 关闭所有文档检查，包括标签兼容性
        addStringOption('-Xdoclint:none', '-quiet')
        // 若只想保留其他检查、仅忽略HTML标签问题，可替换为：
        // addStringOption('-Xdoclint:all,-html', '-quiet')
    }
}

方案3：自定义JavaDoc标签（适合大型项目统一样式） #

通过自定义标签管理注释样式，需两步配置：

1. 在build.gradle中注册自定义标签：

tasks.withType(Javadoc) {
    options {
        addStringOption('tag', 'redText:a:红色文本:')
        addStringOption('tag', 'orangeText:a:橙色文本:')
    }
}

2. 在代码注释中使用自定义标签：

/**
 * Websocket to handle changes.<br>
 * {@redText A RED COMMENT }<br>
 * {@orangeText AN ORANGE COMMENT}
 **/

注：此方案需额外修改JavaDoc样式模板来绑定颜色样式，适合需要统一规范注释样式的场景。

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