使用 Lombok 的 @Builder 注释时出现 Javadoc“找不到符号”错误

Question

I have a class looking as below:

@Data
@Builder
public class Foo {
    private String param;

    /** My custom builder.*/
    public static FooBuilder builder(String _param){
        return builder().param(_param);
    }
}

I get the following error:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.10.4:javadoc (default-cli) on project foo: An error has occurred in JavaDocs report generation:
[ERROR] Exit code: 1 - /home/workspace/foo/src/main/java/com/foo/Foo.java:34: error: cannot find symbol
[ERROR] public static FooBuilder builder(String _param)
[ERROR] ^
[ERROR] symbol: class FooBuilder
[ERROR] location: class Foo

Answer 1

In order to solve this issue, I have to use Lombok's delombok feature (cf : https://projectlombok.org/features/delombok ).

lombok doesn't cover all tools. For example, lombok cannot plug into javadoc ... which run on java sources. Delombok still allows you to use lombok with these tools by preprocessing your java code into java code with all of lombok's transformations already applied.

I did this using Maven by adding the following plugins :

<plugin>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok-maven-plugin</artifactId>
    <version>1.18.0.0</version>
    <configuration>
        <sourceDirectory>${project.basedir}/src/main/java</sourceDirectory>
        <outputDirectory>${delombok.output}</outputDirectory>
        <addOutputDirectory>false</addOutputDirectory>
    </configuration>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>delombok</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <configuration>
        <sourcepath>${delombok.output}</sourcepath>
    </configuration>
</plugin>

Answer 2

Lombok is actually capable of filling out a partially defined builder class, so you can declare enough of the builder to make Javadoc happy and leave it at that. No need to delombok.

The following worked for me in this situation:

@Data
@Builder
public class Foo {
    private String param;

    /** My custom builder.*/
    public static FooBuilder builder(String _param){
        return builder().param(_param);
    }

    public static class FooBuilder {}

}

Side note: that you can actually use this technique to add some customer builder methods, so it has perks. I like to overload builder methods when I have collections so I can items one at a time. There's probably already some technique that does that, but it's nice to know you can improve the builders manually.

Answer 3

Update

If you use maven-javadoc-plugin 3.2.0+ you can configure it like this:

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.2.0</version>
    <configuration>
      <doclint>none</doclint>
    </configuration>
  </plugin>

The doclint configuration will make javadoc plugin not throw an error anymore. It will also disable the lint but if you are ok with this probably the best way to go instead of delombok.

If you use any CI tool to build and compile your project you can create a separated job to check for javadoc lint.

For me disabling lint in the build is not a bad thing. Javadoc is important but shouldn't keep me from building my application just because I'm using Lombok.

Answer 4

Another solution to this would be to not include the BuilderClass in your imports. Instead just import the parent class and change your declaration of the builder type to parentClass.builderClass .

@Getter
@RequiredArgsConstructor
@Builder
public class Foo {
    private final String param;
}

import com.Foo;
//import com.Foo.FooBuilder;

public class Bar {

    public Foo newFoo(String paramValue) {
        Foo.FooBuilder builder = Foo.builder();
        return builder.param(paramValue)
                  .build();
    }

}