java-docs

Java 文档（Javadoc）最佳实践

原则

• 只记录代码实际执行的行为：先阅读实现、调用方和测试。切勿臆造未经验证的行为、阈值、线程安全性、可空性或异常；如有疑问，请省略或询问。
• 遵循项目现有的文档风格（语言、标签顺序、注释形式 /** */ 或 ///）。除非用户要求，否则不要改写现有注释，也不要为整个代码库批量添加文档；将修改限制在请求范围内。
• 使用新特性前，先检查 JDK 级别（maven.compiler.release、工具链、java -version），并确保不超出该级别。

约定

• 仅在 API 实际引入的版本中使用 @since；使用 @deprecated 时，应说明原因和替代方案，并同时添加 @Deprecated。
• 只有项目已在使用 @author 和 @version 时才使用它们。
• 代码块按 JDK 级别处理：
  • 任何 JDK：<pre>{@code ... }</pre>（转义行首的 @，并确保花括号配对）。
  • JDK 18+：内联代码使用 {@snippet : ... }，或使用 {@snippet file="Example.java" region="demo"}，并将文件放在 snippet-files/ 中（示例优先采用此方式；javadoc 不会编译或验证代码片段源文件，因此如需确保这一点，应在单独的构建／测试源集中编译并测试这些文件）。按需使用 // @highlight substring="x" 和 // @replace 标记。
  • 仅限 JDK 23+（JEP 467）：使用 /// 编写 Markdown 文档注释，链接使用 [Type#member]，代码使用围栏代码块。只有项目已采用这种方式或用户提出要求，且构建使用 JDK 23+ 的 javadoc 时才使用。

验证

• 运行 mvn -q javadoc:javadoc（或 ./gradlew javadoc）；对于单个文件，运行 javadoc -Xdoclint:all -d target/javadoc-check <files>；修复引入的所有警告和错误（缺少 @param、HTML 错误、无法解析的 {@link}、未知标签）。
• 说明记录了哪些内容以及运行了哪些命令；指出任何无法根据代码验证的说法。