enhancement: Lombok-generated accessors are absent from the Javadoc

[ebouchut]

What

Javadoc generation was added on the docs/generating-documentation branch (make javadoc → target/reports/apidocs/, published to GitHub Pages under /javadoc/). It has a known blind spot, currently recorded as a caveat in CONTRIBUTING → Generating the Documentation:

The accessors that Lombok generates do not appear in the generated API reference.

Javadoc parses the source, whereas @Getter/@Setter are expanded by Lombok's annotation processor at compile time. The accessors therefore never exist in anything Javadoc reads, and the published API reference shows those classes with their fields documented but with no getX() / setX() methods at all.

Why it matters

The nine classes affected are, without exception, the domain model:

audit/entity/AuditLog          course/entity/Enrollment      role/entity/Role
auth/entity/EmailToken         course/entity/EnrollmentId    user/entity/User
auth/entity/PasswordResetToken course/entity/Lesson
course/entity/Course

So the API reference is at its emptiest precisely where a newcomer (or a DWWM jury member) is most likely to look. A reader of the published Javadoc sees Course as a class with a constructor and essentially no public API, which misrepresents it.

This is not a build defect — nothing is broken, and make javadoc succeeds with zero doclint errors. It is an inherent consequence of combining Lombok with a source-reading documentation tool.

How to fix it

The standard remedy is delombok: expand the Lombok annotations into ordinary Java source, and point Javadoc at the expanded sources instead of src/main/java.

A useful bonus: delombok carries a field's Javadoc over to the accessors it generates (Lombok honours GETTER: / SETTER: sections in a field comment). So delomboking does not merely make the accessors appear — it lets us document them from the field comment we already write.

Option A — lombok-maven-plugin (the classic route)

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

and then, on maven-javadoc-plugin:

<sourcepath>${project.build.directory}/generated-sources/delombok</sourcepath>

⚠️ Checked against Maven Central: the newest release of lombok-maven-plugin is 1.18.20.0, published 2021-04-02 — roughly five years behind the Lombok this project actually uses (1.18.46, managed by the Spring Boot parent). Introducing a long-abandoned plugin, pinned to a 2021-era Lombok, into a Java 21 build is the single biggest risk in this issue.

Option B — call Lombok's own delombok (no third-party plugin) — preferred

Lombok ships the delombok entry point itself (lombok.launch.Main delombok). Invoke it with exec-maven-plugin against the Lombok artifact already on the build path, so we always delombok with the exact Lombok version we compile with, and add no unmaintained dependency:

java -cp <lombok.jar> lombok.launch.Main delombok src/main/java -d target/generated-sources/delombok

Wire it into a profile (or only into the javadoc Make target) so the normal build (make test, ./mvnw package) is untouched — matching the current design, where the Javadoc plugin is bound to no lifecycle phase.

Option C — change nothing

Keep the caveat documented in CONTRIBUTING (the status quo).

Trade-offs

In favour of fixing

• The API reference would finally reflect the real public API of the domain model — the most-read classes in the project.
• Field Javadoc could flow into the accessors, so the entities become genuinely self-documenting.
• A complete API reference is a better artefact to show at the DWWM defence.

Against fixing / risks

• Option A adds an unmaintained plugin (last release 2021) to a Java 21 build. Option B avoids that but is more DIY and needs the Lombok jar path resolved.
• A second copy of every source file appears under target/generated-sources/delombok. It must never reach the compile source roots (addOutputDirectory=false), or we risk duplicate-class errors and confused coverage/line numbers.
• The docs would then be generated from derived rather than authored source, so line references no longer map 1:1 to the repository.
• Extra build time on every Javadoc run (delombok re-expands the whole source tree).
• Without field Javadoc, the accessors would show up but undocumented — potentially a wall of empty getTitle() / setTitle() entries, which is arguably noisier rather than clearer. Getting the benefit means also writing the field comments.
• It is maintenance surface for a documentation-only gain: the accessors are trivial and entirely predictable, and the fields they expose are already documented.
• Cuts against the project's report-don't-over-engineer stance (ADR-0011).

Recommendation

Option B, or a considered Option C. The deciding question is whether the published API reference is an artefact anyone will actually read (jury, future contributors) — if yes, the incompleteness is worth removing; if not, the documented caveat is honest and free.

If we change the build, the decision is worth an ADR, since it introduces a generated-source stage.

Acceptance criteria

• Decision taken and recorded (an ADR if the build changes).
• If fixed: the accessors of User, Course, Lesson, Enrollment (and the other five entities) appear in target/reports/apidocs/ and on the published Pages site.
• make test still passes and the Javadoc plugin remains bound to no lifecycle phase — the normal build must not pay for delombok.
• No duplicate sources reach the compile source roots.
• The caveat in CONTRIBUTING is updated or removed accordingly.

References

• Caveat as documented today: CONTRIBUTING.md → Generating the Documentation → API Reference (Javadoc)
• Introduced by branch docs/generating-documentation (Javadoc plugin, make javadoc, Pages publishing)