From 02c68c112df20ec7b3f2cdc492606237c68e3826 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Fri, 21 Aug 2026 02:38:25 +0200 Subject: [PATCH] [docs][config: `lombok.CheckReturnValue`] --- website/templates/features/Builder.html | 2 ++ website/templates/features/SuperBuilder.html | 2 ++ website/templates/features/configuration.html | 7 +++++-- 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/website/templates/features/Builder.html b/website/templates/features/Builder.html index 4fd90741..0449620f 100644 --- a/website/templates/features/Builder.html +++ b/website/templates/features/Builder.html @@ -234,6 +234,8 @@ public class JacksonExample { protected keyword is different inside the inner class, and the precise behavior that PROTECTED would indicate (access by any source in the same package is allowed, as well as any subclasses from the outer class, marked with @Builder is not possible, and marking the inner members public is as close as we can get.

If you have configured a nullity annotation flavour via lombok.config key lombok.addNullAnnotations, any plural-form generated builder methods for @Singular marked properties (these plural form methods take a collection of some sort and add all elements) get a nullity annotation on the parameter. You get a non-null one normally, but if you have configured the behavior on null being passed in as collection to IGNORE, a nullable annotation is generated instead. +

+ The generated build() method will be annotated to indicate that callers must not ignore the returned value if you ask lombok to do this via the lombok.checkReturnValueAnnotation configuration key. However, if applying @Builder to a method, lombok doesn't add such an annotation, unless the method you marked with @Builder is itself marked with any annotation that implies 'check return value', including annotations that indicate side effect free or pure. If @Builder is applied to an explicitly written constructor, the @CheckReturnValue annotation will be added to the build() method if requested, even though constructors can in theory have side effects, and thus, ignoring the return value could be acceptable. Nevertheless, lombok assumes all constructors have no effect other than making an object, and you cannot override this assumption.

diff --git a/website/templates/features/SuperBuilder.html b/website/templates/features/SuperBuilder.html index bc682468..0af65b85 100644 --- a/website/templates/features/SuperBuilder.html +++ b/website/templates/features/SuperBuilder.html @@ -86,6 +86,8 @@ For remarks on @Singular, see the @Builder documentation's small print.

Various well known annotations about nullity cause null checks to be inserted and will be copied to parameter of the builder's 'setter' method. See Getter/Setter documentation's small print for more information. +

+ The generated build() method will be annotated to indicate that callers must not ignore the returned value if you ask lombok to do this via the lombok.checkReturnValueAnnotation configuration key. While in theory constructors can have side effects, lombok always assumes they do not, and you cannot override this assumption.

diff --git a/website/templates/features/configuration.html b/website/templates/features/configuration.html index a09b0c81..fc96e0f0 100644 --- a/website/templates/features/configuration.html +++ b/website/templates/features/configuration.html @@ -90,11 +90,14 @@ Many flavors are available: jspecify (recommended), checkerframework (recommended), jakarta, eclipse, jetbrains, netbeans, androidx, findbugs, spring, jml, javax (=JSR305; not recommended), android.support (deprecated within android), or define your own via CUSTOM:fully.qualified.NonNullAnnotation:fully.qualified.NullableAnnotation; if your nullity annotation is solely of the type use style (it annotates types, such as eclipse's and checkerframework's offerings, versus annotating methods and parameters), the format is CUSTOM:TYPE_USE:nonnullanno:nullableanno.
This feature was added in lombok v1.18.12.

- Lombok can add a @CheckReturnValue annotation to generated methods whose return value should not be ignored, such as withX methods and @Builder's build() method. Static analysis tools (IntelliJ, Error Prone, SpotBugs) will then warn when callers discard the result. By default, no such annotation is added. Enable with: + Lombok can add annotations to methods it generates if code that invokes this method should always to something with the returned value. For example, withX methods, and @Builder's build() method.
+ Lombok ships with its own take on this annotation named @lombok.CheckReturnValue. Static analysis tools (IntelliJ, Error Prone, SpotBugs) will then warn when callers discard the result. By default, no such annotation is added. Enable with:

  1. lombok.checkReturnValueAnnotation = <flavor>
- Currently the only non-none flavor is lombok, which emits @lombok.CheckReturnValue. A future lombok release may flip the default to lombok.
+ Supported flavors are: lombok, as well as androidx which emits @androidx.annotation.CheckResult.
+ Default: none. A future lombok release may flip the default to lombok.
+ This feature was added in lombok v1.18.48.

Lombok can be configured to add @lombok.Generated annotations to all generated nodes where possible; useful for JaCoCo (which has built in support), or other style checkers and code coverage tools: