先看看示例
作者提供的示例，实际效果取决于你的输入和使用工具。
输入
为新增的订单校验类补 Javadoc，写明参数与异常，沿用项目现有标签顺序，并运行 javadoc 检查。
输出
预期交付：补充或修正的 Javadoc 注释，以及 javadoc 校验结果说明。（编辑说明，非实际运行结果）
方法说明
---
name: java-docs
description: 'Ensure that Java types are documented with Javadoc comments and follow best practices for documentation.'
---
# Java Documentation (Javadoc) Best Practices
## Principles
- Document only what the code actually does: read the implementation, callers and tests first. Never invent behaviour, thresholds, thread-safety, nullability or exceptions you have not verified; if unsure, leave it out or ask.
- Keep the existing documentation style of the project (language, tag order, comment form `/** */` vs `///`). Do not rewrite existing comments, or mass-document a codebase, unless the user asks; limit changes to the requested scope.
- Check the JDK level (`maven.compiler.release`, toolchain, `java -version`) before using newer features, and stay within it.
## Conventions
- `@since` only with the real version in which the API was introduced; `@deprecated` with a reason and replacement, together with `@Deprecated`.
- `@author` and `@version` only if the project already uses them.
- Code blocks, by JDK level:
- Any JDK: `<pre>{@code ... }</pre>` (escape `@` at line start, balance braces).
- JDK 18+: `{@snippet : ... }` for inline code, or `{@snippet file="Example.java" region="demo"}` with files in `snippet-files/` (preferred for examples; `javadoc` does not compile or validate the snippet source, so compile and test the files in a separate build/test source set if you need that guarantee). Use `// @highlight substring="x"` and `// @replace` markup as needed.
- JDK 23+ only (JEP 467): Markdown doc comments with `///`, using `[Type#member]` for links and fenced code blocks. Use them only if the project already does or the user asks, and the build runs a JDK 23+ `javadoc`.
## Verify
- Run `mvn -q javadoc:javadoc` (or `./gradlew javadoc`) and for single files `javadoc -Xdoclint:all -d target/javadoc-check <files>`; fix every warning/error you introduced (missing `@param`, bad HTML, unresolved `{@link}`, unknown tags).
- Report what was documented and the commands run; state any claims you could not verify from the code.