Copy Javadoc to @Builder setters

[emlun]

Re-implementation of #2004 on top of the fixes made in ccfab5e. Fixes #1033. Fixes #1445.

Forum discussion: https://groups.google.com/forum/#!topic/project-lombok/aZx5wJp891k

This still makes no attempt to include @Singular versions of builder methods, because that requires some nontrivial decision making. Had the plural version been equivalent to the standard non-@Singular version, it would be simple enough to copy the docstring to the plural method and auto-generate docstrings for the singular and clearer referencing that of the plural. Unfortunately, the plural version is subtly but importantly different - it doesn't replace the collection but instead adds elements to it - so it's probably not a good idea to just drop a standard setter docstring on it.

An alternative approach to extending this to @Singular methods would be to add a couple of new docstring section types: SINGULAR, PLURAL, CLEAR for example, and not generate a docstring if the corresponding section doesn't exist.

Anyway, extending this to @Singular versions can just as well be done in a separate PR.

[rspilker]

Looks good!

[emlun]

Thanks! 😄

[rzwitserloot]

this is now available in edge release: https://projectlombok.org/download-edge

[badgerwithagun]

@rzwitserloot thanks for this! I've just given it a try and noticed that it's not elevating the Javadoc if @Builder is used on a constructor, e.g.

public class Example {

  /** I expect this to appear on the builder */
  private final String arg;

  @Builder
  private Example(String arg) {
    this.arg = arg;
  }
}

Any way around this?

[badgerwithagun]

In fact, it doesn't seem to work at all, regardless of how I use @Builder.

Class with:

  /**
   * @param foo Bar
   */
  @SuppressWarnings("JavaDoc")
  @Builder.Default
  @NotNull
  private final int foo= 2;

Produces the builder method:

    @java.lang.SuppressWarnings("all")
    public B foo(final int foo) {
      ..
    }

With delombok plugin:

          <plugin>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok-maven-plugin</artifactId>
            <version>1.18.12.0</version>
            <dependencies>
              <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>edge-SNAPSHOT</version>
              </dependency>
            </dependencies>
            <executions>
              <execution>
                <id>delombok</id>
                <phase>generate-sources</phase>
                <goals>
                  <goal>delombok</goal>
                </goals>
                <configuration>
                  <addOutputDirectory>false</addOutputDirectory>
                  <sourceDirectory>src/main/java</sourceDirectory>
                </configuration>
              </execution>
            </executions>
          </plugin>

[mathisdt]

I don't know if this is related, but I don't get Javadoc either. Using Lombok 1.18.12 in Eclipse 2020-03, none of the following classes generates Javadoc on the number builder method:

@Builder
public class Test1 {
    /** Comment on Field */
    private int number;

    /** @param number Comment on Constructor */
    public Test1(final int number) {
        this.number = number;
    }

    private void bla() {
        Test1.builder()
            .number(1) // <--- no Javadoc displayed in tooltip
            .build();
    }
}

public class Test2 {
    /** Comment on Field */
    private int number;

    /** @param number Comment on Constructor */
    @Builder
    public Test2(final int number) {
        this.number = number;
    }

    private void bla() {
        Test2.builder()
            .number(1) // <--- no Javadoc displayed in tooltip
            .build();
    }
}