Generate Lombok documentation using IntelliJ

by

Summary

The issue at hand is the inability to generate Lombok documentation using IntelliJ. Despite having the Lombok plugin installed and annotation processing enabled, the generated Javadoc does not include the getter and setter methods. This is a common problem encountered by developers using Lombok with IntelliJ.

Root Cause

The root cause of this issue is that Lombok does not actually generate the getter and setter methods until compile-time. As a result, IntelliJ does not see these methods at design-time, and therefore does not include them in the generated Javadoc. The key causes are:

  • Lombok’s compile-time generation of methods
  • IntelliJ’s design-time analysis of code
  • Javadoc generation relying on visible methods

Why This Happens in Real Systems

This issue occurs in real systems because of the way Lombok and IntelliJ interact. Lombok is designed to reduce boilerplate code, but its compile-time generation of methods can sometimes cause issues with IDEs like IntelliJ. The reasons include:

  • Lombok plugins not fully integrating with IDEs
  • IDE limitations in handling compile-time generated code
  • Javadoc generation not accounting for Lombok’s behavior

Real-World Impact

The impact of this issue is that developers may not have accurate or complete documentation for their classes. This can lead to:

  • Incomplete or inaccurate documentation
  • Difficulty for other developers to understand the code
  • Potential errors or misunderstandings when using the classes

Example or Code

import lombok.AllArgsConstructor;
import lombok.EqualsAndHashCode;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.NonNull;
import lombok.Setter;
import lombok.ToString;

@Getter
@Setter
@EqualsAndHashCode
@ToString
@NoArgsConstructor
@AllArgsConstructor
public class Author {
    private int id;
    private String name;
    private String surname;
    private String email;
    private final String birthPlace = "Somewhere";

    /**
     * This is the constructor of the Author class
     * 
     * @param id      This is the author identifier
     * @param name    This is the first name of the author
     * @param surname This is the last name of the author
     */
    public Author(@NonNull int id, @NonNull String name, String surname) {
        this.id = id;
        this.name = name;
        this.surname = surname;
    }
}

How Senior Engineers Fix It

Senior engineers can fix this issue by using the delombok tool to generate the expanded source code, and then running Javadoc on the expanded code. This ensures that all methods, including those generated by Lombok, are included in the documentation. The steps are:

  • Use delombok to expand the Lombok annotations
  • Run Javadoc on the expanded code
  • Use the resulting documentation as the accurate and complete documentation for the classes

Why Juniors Miss It

Junior engineers may miss this issue because they:

  • Are not familiar with the Lombok plugin and its behavior
  • Do not understand how IntelliJ generates Javadoc
  • Are not aware of the delombok tool and its purpose
  • Do not recognize the importance of accurate and complete documentation
  • May not have experience with the limitations of IDE integration with Lombok and Javadoc generation. Key takeaways include understanding Lombok behavior, IDE limitations, and the importance of accurate documentation.

Leave a Comment