JEP 224：HTML5 Javadoc

QWen Max 中英对照

概述

增强 javadoc 工具以生成 HTML5 标记。

目标

为标准 doclet 提供一个选项，以请求生成 HTML 4 或 HTML5 输出。HTML5 标记是语义化的，即清晰地将含义与样式和内容分离。使用 HTML5 标记生成的标准 doclet 页面部分满足无障碍访问要求。

非目标

取代当前生成的 HTML 页面的三框架/无框架结构并不是目标；这可能是未来 JEP 的主题。

强制要求在文档注释中使用 HTML5 不是目标，提供将使用 HTML 4 编写的文档注释转换为 HTML5 的能力也不是目标。

动机

在 JDK 8 和更早的版本中，标准文档生成工具生成的页面使用的是 HTML 4.01，这是一个较旧的标准，并且不提供对满足可访问性要求的支持。
HTML5 是 HTML 的最新标准。HTML5 提升了网页的语义价值，并使创建可访问的网页变得更加容易。

描述

• 为标准 doclet 添加了一个命令行选项，用于请求特定类型的输出标记。当前类型为 HTML4，其将是默认值。HTML5 将在 JDK 10 中成为默认值。

• 使用结构性的 HTML5 元素（例如 header、footer、nav 等等）提高了生成的 HTML 的语义价值。

• HTML5 标记实现了 WAI-ARIA 标准以提高可访问性。使用 role 属性为 HTML 文档中的元素分配了特定的角色。

• -Xdoclint 功能更新为基于所请求的输出标记类型检查文档注释是否存在常见错误。

测试

提供测试以确保：

• HTML5 标记是有效的
• HTML5 标记是可访问的
• 新的命令行选项可以正确工作
• HTML5 标记在所有支持的浏览器中都能正常工作

缺乏自动化的工具来测试可访问性阻碍了全面的可访问性测试。可以使用基于网页的在线工具检查不同类型页面的代表性样本。