质量外联提示 - JDK 28：丰富的JavaDoc注释
内容提要
OpenJDK质量组推动用OpenJDK构建测试FOSS项目以提升发布质量，并提议新增JavaDoc标签@note，用于标注API使用提示或警告，支持内联和块级显示，可通过属性自定义标题、样式和ID，并允许用-tag选项创建别名标签。详情见JDK-8363700。
延伸解读
质量外联与FOSS测试的关联
OpenJDK质量组推动用OpenJDK构建测试FOSS项目，旨在提升发布质量。这一外联提示是发给参与项目的更新的一部分，说明该测试计划与JDK 28的JavaDoc改进同属质量提升工作。读者可关注该计划如何通过实际项目反馈影响JDK开发。
@note标签的实用价值
@note标签用于标注API使用提示或警告，支持内联和块级显示。内联笔记左侧有竖条突出，块级笔记有缩进和标题。开发者可通过header、kind、id等属性自定义标题、样式和ID，使文档更清晰。这有助于减少API误用，提升代码可维护性。
自定义标签的灵活性
通过javadoc -tag选项，可将@note别名为其他标签，如@warning。示例中创建@warning标签后，使用{@warning ...}会渲染为“Warning:”标题。这种别名机制允许团队根据项目规范定制标签，统一文档风格，但需注意别名标签的渲染行为与@note一致。
反馈与后续关注
该提案详情见JDK-8363700，反馈可通过javadoc-dev邮件列表提交（需注册）。目前@note仍处于提议阶段，尚未成为标准。开发者应关注其最终是否纳入JDK 28，以及属性支持范围是否变化，避免过早依赖未定特性。
Q&A
OpenJDK质量组为什么要推动用OpenJDK构建测试FOSS项目？
为了提升OpenJDK发布的整体质量。
JavaDoc新提议的@note标签有什么作用？
用于标注API使用提示或警告，帮助开发者注意有用信息或潜在问题。
@note标签支持哪些显示方式？
支持内联和块级显示。内联笔记左侧有竖线突出显示；块级笔记有默认标题和缩进文本。
如何自定义@note标签的标题、样式和ID？
可以通过属性来自定义，例如header属性修改标题，kind属性添加CSS类，id属性添加HTML id。
能否为@note创建别名标签？如何操作？
可以，使用javadoc -tag选项创建别名标签，例如定义@warning作为@note的别名。
在哪里可以找到关于@note的更多细节和反馈渠道？
更多细节见JDK-8363700，反馈可通过javadoc-dev邮件列表（需注册）。
