如何使用JavaDoc为Builder及其方法编写规范技术文档？

一、Builder类的类级JavaDoc（全局统一说明） #

直接在Builder类的类注释里集中梳理核心规则，把必填项、可选项（含默认值）分类列出，避免规则分散在各个方法里。示例写法：

/**
 * 用于构建{@link ComplexObject}的建造器
 * <p><b>必填配置项</b>：
 * <ul>
 *   <li>{@link #setRequiredFoo(String)}: 核心业务标识，无默认值，必须调用</li>
 *   <li>{@link #addRequiredBaz(int)}: 至少添加1个业务参数，否则构建失败</li>
 * </ul>
 * <p><b>可选配置项（带默认值）</b>：
 * <ul>
 *   <li>{@link #withOptionalBar(boolean)}: 是否启用扩展功能，默认值为{@code false}</li>
 *   <li>{@link #setOptionalTimeout(int)}: 请求超时时间，默认值为{@code 3000}毫秒</li>
 * </ul>
 * <p>使用示例：
 * <pre>{@code
 * ComplexObject obj = new ComplexObject.Builder()
 *     .setRequiredFoo("user_123")
 *     .addRequiredBaz(45)
 *     .withOptionalBar(true)
 *     .build();
 * }</pre>
 */
public static class Builder {
    // 建造器实现
}

用加粗标签区分分类，列表直接关联对应方法链接，再配上代码示例，使用者一眼就能掌握全局配置规则。

二、方法级JavaDoc补全细节 #

每个Builder方法的注释不用重复类级里的“必填/可选”说明，只补充类级没覆盖的细节，比如参数约束、特殊逻辑：

/**
 * 设置核心业务标识
 * @param foo 不能为null或空字符串，否则{@link #build()}会抛出{@link IllegalArgumentException}
 * @return 当前Builder实例，支持链式调用
 */
public Builder setRequiredFoo(String foo) {
    // 实现逻辑
}

/**
 * 添加业务参数
 * @param baz 必须大于0，小于100，超出范围的参数会被自动过滤
 * @return 当前Builder实例，支持链式调用
 */
public Builder addRequiredBaz(int baz) {
    // 实现逻辑
}

三、build()方法明确校验规则 #

在build()方法的注释里说明未满足必填项时的行为，比如抛出异常的类型：

/**
 * 构建{@link ComplexObject}实例
 * @throws IllegalArgumentException 当必填项未配置、配置不合法，或业务参数数量不足时抛出
 * @return 配置完成的ComplexObject实例
 */
public ComplexObject build() {
    // 校验+构建逻辑
}

四、工具辅助增强文档效果 #

如果原生JavaDoc的表现力不够，可以结合以下工具优化：

• Lombok：用@Builder自动生成建造器，配合@NonNull标记必填属性，Lombok会自动在生成的JavaDoc里标注必填项；用@Builder.Default指定可选属性的默认值，生成的注释也会包含这些默认值信息。
• 自定义JavaDoc标签：团队内部可以约定@required、@defaultValue等自定义标签，比如在方法注释里加@required标记必填项，再用自定义Doclet工具解析这些标签，生成更结构化的文档（适合大型项目统一规范）。
• 代码规范工具：用Checkstyle或SpotBugs配置规则，强制Builder方法的命名风格（比如统一用withXxx或setXxx），让注释和代码风格更一致，降低理解成本。

内容的提问来源于stack exchange，提问作者Léa Gris