JavaDoc是调用方理解接口契约的第一手依据，需完整覆盖接口设计意图、每个public方法的行为目的与约束条件，并用{@code}和{@link}增强可读性，附最小可行示例。
接口的JavaDoc不是可有可无的说明，而是调用方理解契约的第一手依据。写得清楚，能大幅减少沟通成本和误用风险。
接口与方法级注释必须完整
接口本身需用一段话讲清设计意图和使用边界，比如“提供用户身份校验能力，适用于登录、权限前置检查等场景”。每个public方法都要有独立的JavaDoc块，不能省略。空方法或默认实现也得写——哪怕只有一句“不执行任何操作，供子类重写”。
- 接口注释开头用完整句子概括职责，结尾用英文句号
- 方法注释首行描述行为目的，避免“实现XX逻辑”这类实现细节表述
- 所有public成员（包括常量）都应覆盖，private方法可不写
@param、@return、@throws要写实不写虚
参数说明不能只写“用户名”，而要写“username：用户登录名，长度3–20位，仅含字母、数字和下划线，不能为空”。返回值要明确null是否合法、集合是否可能为空、对象字段是否全部填充。异常说明必须对应真实抛出点，比如@throws IllegalArgumentException后面跟上“当token过期或签名无效时抛出”。
- 每个@param单独一行，紧接参数名，不加冒号或括号
- @return在void方法中不出现；非void方法必须说明返回内容的业务含义
- @throws只列实际声明或明确抛出的受检/非受检异常，不写“可能抛出运行时异常”这种模糊表述
善用内联标签提升可读性
代码元素统一用{@code }包裹，比如{@code List<User>}、{@code userId}。跨类引用用{@link }，例如{@link UserService#login(String, String)}，IDE能跳转，生成文档里会自动转为超链接。关键约束条件可加强调，如“该方法线程不安全，并发调用需自行同步”。
立即学习“Java免费学习笔记（深入）”；
- 类型、变量名、方法名、字面量一律用{@code}，避免HTML转义问题
- {@link}优先用简写形式（当前包内类可省包名），确保链接有效
- 避免大段纯文本描述，适当用
<p>分段或<ul>罗列前提条件
附带最小可行示例
在方法JavaDoc末尾加一个@example段落，给出2–4行真实调用代码。不追求功能完整，只展示最典型用法。比如登录方法配User user = service.login("admin", "123");，查询方法配List<Order> list = service.listByStatus(OrderStatus.PAID);。示例中涉及的类和参数名必须与接口定义完全一致。
- 示例代码不包含try-catch包装，突出核心调用链
- 避免硬编码敏感值（如密码写"***"而非明文）
- 若方法有多种常用组合，可并列两个简洁示例
