Javadoc 警告：使用 Lombok @Builder 时没有类型的 @param答案

【问题标题】：Javadoc warning: no @param for type when using Lombok @BuilderJavadoc 警告：使用 Lombok @Builder 时没有类型的 @param
【发布时间】：2022-01-24 18:22:03
【问题描述】：

当从源代码（delomboked）生成 javadoc 时，我收到以下由 Lombok 的 @Builder 生成的构建器类的警告

[ERROR] Error while creating javadoc report: 
Exit code: 1 - /path/to/project/ProjectData.java:85: warning: no @param for type
        public ProjectData.ProjectDataBuilder type(final ProjectType type) {

这是引起警告的delomboked类的一部分：

/**
 * @return {@code this}.
 */
@java.lang.SuppressWarnings("all")
public ProjectData.ProjectDataBuilder type(final ProjectType type) {
    this.type = type;
    return this;
}

这是假定的正确的、不产生警告的 javadoc - 存在 @param

/**
 * @param type some meaningful description
 * @return {@code this}.
 */
@java.lang.SuppressWarnings("all")
public ProjectData.ProjectDataBuilder type(final ProjectType type) {
    this.type = type;
    return this;
}

有没有办法让 de-lombok 也生成这些？我的项目中有很多这样的警告，它们掩盖了所有相关的实际错误。

【问题讨论】：

type 字段声明中的 JavaDoc 是什么？
可以说，您的“没有产生警告的 javadoc”应该产生警告。那行“代码”中绝对没有任何价值您会看到参数的名称。好吧，这已经在代码中了。我希望那种类型的 javadoc 或类似的 @param type the type 会被标记。
@JanRieke 没有。但是正如您所提到的 - 我已经添加了一些并将其复制到 delomboked 类中的字段以及它放置在该字段的构建器方法上。问题在于它是 1:1 复制的，所以它只是对该方法的描述，而 @param 是“不允许”覆盖原始文件中的字段的。
@RoelSpilker 是的，你是绝对正确的，我已经编辑了这个问题。当然我想在那里有一些有意义的信息，而不仅仅是“类型”或“类型”：D

标签： java javadoc lombok

【解决方案1】：

使用最新的 Lombok 版本¹，delombok 会将放置在字段 Javadoc 中的 @param 复制到相应的构建器方法中。

这是现有@Getter/@Setter 功能的扩展，该功能已将@param/@return 移动到相应的setter/getter。

您还可以选择性地使用-- SETTER --/-- GETTER -- 放置完全自定义的文档（在这种情况下，@param 和 @return 标记必须位于相应的部分）：

@Builder
@Data
@AllArgsConstructor
public class LombokJavadoc {
    /**
     * my nice field
     *
     * -- SETTER --
     * sets the something
     *
     * @param something a nice value
     * -- GETTER --
     * access for something
     *
     * @return a nice value
     */
    private String something;
}

生成：

public class LombokJavadoc {
    /**
     * my nice field
     */
    private String something;


    @java.lang.SuppressWarnings("all")
    public static class LombokJavadocBuilder {
        […]

        /**
         * sets the something
         *
         * @param something a nice value
         * @return {@code this}.
         */
        @java.lang.SuppressWarnings("all")
        public LombokJavadoc.LombokJavadocBuilder something(final String something) {
            this.something = something;
            return this;
        }
    }

    […]

    /**
     * access for something
     *
     * @return a nice value
     */
    @java.lang.SuppressWarnings("all")
    public String getSomething() {
        return this.something;
    }

    /**
     * sets the something
     *
     * @param something a nice value
     */
    @java.lang.SuppressWarnings("all")
    public void setSomething(final String something) {
        this.something = something;
    }
    
    […]
}

¹ 这似乎实际上已在 PR #2008 中实现，它是 v1.18.6 的一部分

【讨论】：