要让Java注释生成规范API文档，必须使用/*开头、/结尾的文档注释，紧贴public类、方法、字段声明上方；正确使用@param（参数名须一致）和@return（说明业务含义）；生成时需指定-encoding UTF-8等参数防乱码，并用-private显示private成员。
要让 Java 注释生成规范的 API 文档，核心是写对 文档注释，并确保它能被 javadoc 工具正确识别和提取。不是所有注释都管用，只有以 /** 开头、*/ 结尾的块注释，且位置紧贴在类、方法、字段等声明上方时，才有效。
必须用标准文档注释格式
文档注释不是普通多行注释（/* */）或单行注释（//），必须是：
- 以
/**开始，*/结束 - 紧挨着被描述的元素（如方法、类、public 字段）上方，中间不能有空行
- 支持 HTML 标签和 Javadoc 专用标签（如
@param、@return）
@param 和 @return 要准确对应参数与返回值
这两个标签不是可有可无的装饰，而是生成文档的关键结构信息：
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
-
@param 参数名 描述：参数名必须和方法签名中完全一致（包括大小写），描述要说明用途、取值范围或约束条件 -
@return 描述：说明返回值的业务含义，不是简单重复类型（比如不要写“返回 int”，而应写“返回用户积分余额，为负数表示欠费”） - 如果方法有多个参数，每个都要单独写
@param；若无返回值（void），就不加@return
公共 API 必须全覆盖，私有成员按需补充
生成文档的目标是服务使用者，所以重点在对外暴露的部分：
立即学习“Java免费学习笔记（深入）”；
- 所有
public类、接口、方法、常量字段，都应有完整 JavaDoc -
protected成员若可能被子类使用，也建议添加 - 私有方法（
private）是否加文档，取决于逻辑复杂度——如果做了关键校验、状态转换或有隐含约定，就值得写 - 简单的 getter/setter（如
getName()）通常可省略，除非行为特殊（比如带缓存、触发计算）
生成环节要注意编码和可见性设置
写了规范注释，不代表文档一定清晰可用。常见问题往往出在生成阶段：
- 中文乱码？加参数：
-encoding UTF-8 -docencoding UTF-8 -charset UTF-8 - private 方法没出现在文档里？加上
-private参数 - 自定义注解不显示？确认注解类本身有 JavaDoc，并标注了
@Documented、@Retention(RUNTIME)、@Target - 在 IntelliJ IDEA 中生成时，记得在 “Other command line arguments” 里填入上述参数，并将 Locale 设为
zh_CN（如需中文界面）
