[feature][@CheckReturnValue] Replace boolean opt-in with enum-valued lombok.checkReturnValueAnnotation config key.

Per PR #4013 review, swap the boolean `lombok.addCheckReturnValueAnnotation`
for an enum-valued `lombok.checkReturnValueAnnotation` (values: `none`,
`lombok`; default: `none`). This leaves room for additional flavors
(`jetbrains`, `errorprone`, `custom: FQN`) in future releases without
another key rename, and for flipping the default to `lombok` after a
release cycle or two.

# Conflicts:
#	doc/changelog.markdown

doc/changelog.markdown

@@ -3,6 +3,7 @@ Lombok Changelog
 
 ### v1.18.47 "Edgy Guinea Pig"
 * BUGFIX: `@SneakyThrows` usage on JDK26 no longer results in class files that require `lombok.jar` to be on the runtime classpath (which should not be neccessary). [#4040](https://github.com/projectlombok/lombok/issues/4022).
+* FEATURE: New [config key](https://projectlombok.org/features/configuration) `lombok.checkReturnValueAnnotation` (values: `none`, `lombok`; default: `none`) lets lombok generate `@lombok.CheckReturnValue` on generated methods where the return value should not be ignored, such as `@With` methods and `@Builder.build()`. A future lombok release may flip the default to `lombok`. [#4013](https://github.com/projectlombok/lombok/pull/4013).
 * PROMOTION: `@SuperBuilder` has been promoted to the main package. Otherwise, no changes have been made to the annotation. The old experimental annotation will remain for a few versions, at which point it will be marked as a deprecated annotation. Eventually it'll be removed. If you had `lombok.config` configuration for this annotation, the configuration keys for this feature have been renamed.
 * OLD-CRUFT: `lombok.experimental.Wither` and `lombok.Delegate` are deprecated remnants; these features were moved (to respectively `lombok.With` and `lombok.experimental.Delegate` over 5 years ago. They are now removed entirely. If your project is dependent on an older version of lombok which still has those; fret not, lombok still processes these annotations. It just no longer includes them in the jar.
 

src/core/lombok/CheckReturnValue.java

@@ -35,7 +35,7 @@ import java.lang.annotation.Target;
  * Static analysis tools (Error Prone, IntelliJ, SpotBugs) recognize {@code @CheckReturnValue}
  * by simple class name, regardless of package, and will warn when the return value is discarded.
  * <p>
- * If you want to opt in, you can add {@code lombok.addCheckReturnValueAnnotation = true} to
+ * If you want to opt in, you can add {@code lombok.checkReturnValueAnnotation = lombok} to
  * {@code lombok.config}.
  */
 @Target({ElementType.METHOD})

src/core/lombok/ConfigurationKeys.java

@@ -25,6 +25,7 @@ import java.util.List;
 
 import lombok.core.configuration.CallSuperType;
 import lombok.core.configuration.CapitalizationStrategy;
+import lombok.core.configuration.CheckReturnValueFlavor;
 import lombok.core.configuration.CheckerFrameworkVersion;
 import lombok.core.configuration.ConfigurationKey;
 import lombok.core.configuration.FlagUsageType;
@@ -91,12 +92,13 @@ public class ConfigurationKeys {
 	public static final ConfigurationKey<Boolean> ADD_LOMBOK_GENERATED_ANNOTATIONS = new ConfigurationKey<Boolean>("lombok.addLombokGeneratedAnnotation", "Generate @lombok.Generated on all generated code (default: true).") {};
 
 	/**
-	 * lombok configuration: {@code lombok.addCheckReturnValueAnnotation} = {@code true} | {@code false}.
+	 * lombok configuration: {@code lombok.checkReturnValueAnnotation} = [{@code none} | {@code lombok}].
 	 *
-	 * If {@code true}, lombok generates {@code @lombok.CheckReturnValue} on generated methods where the return value should not be ignored,
+	 * If set to {@code lombok}, lombok generates {@code @lombok.CheckReturnValue} on generated methods where the return value should not be ignored,
 	 * such as {@code @With} methods and {@code @Builder}'s {@code build()} method.
+	 * If set to {@code none} (the current default), no such annotation is emitted. A future lombok release may flip the default to {@code lombok}.
 	 */
-	public static final ConfigurationKey<Boolean> ADD_CHECK_RETURN_VALUE_ANNOTATIONS = new ConfigurationKey<Boolean>("lombok.addCheckReturnValueAnnotation", "Generate @lombok.CheckReturnValue on generated methods where the return value should not be ignored (default: false).") {};
+	public static final ConfigurationKey<CheckReturnValueFlavor> CHECK_RETURN_VALUE_ANNOTATION = new ConfigurationKey<CheckReturnValueFlavor>("lombok.checkReturnValueAnnotation", "Which @CheckReturnValue annotation flavor to emit on generated methods. Values: none, lombok (default: none).") {};
 
 	/**
 	 * lombok configuration: {@code lombok.extern.findbugs.addSuppressFBWarnings} = {@code true} | {@code false}.

src/core/lombok/core/configuration/CheckReturnValueFlavor.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2026 The Project Lombok Authors.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package lombok.core.configuration;
+
+/** Used for lombok configuration to select which {@code @CheckReturnValue} annotation flavor to emit on generated methods. */
+public enum CheckReturnValueFlavor {
+	NONE, LOMBOK;
+}

src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java

@@ -116,6 +116,7 @@ import lombok.core.AnnotationValues;
 import lombok.core.AnnotationValues.AnnotationValue;
 import lombok.core.LombokImmutableList;
 import lombok.core.TypeResolver;
+import lombok.core.configuration.CheckReturnValueFlavor;
 import lombok.core.configuration.CheckerFrameworkVersion;
 import lombok.core.configuration.NullAnnotationLibrary;
 import lombok.core.configuration.NullCheckExceptionType;
@@ -2128,8 +2129,15 @@ public class EclipseHandlerUtil {
 	}
 	
 	public static Annotation[] addCheckReturnValue(EclipseNode node, ASTNode source, Annotation[] originalAnnotationArray) {
-		if (!Boolean.TRUE.equals(node.getAst().readConfiguration(ConfigurationKeys.ADD_CHECK_RETURN_VALUE_ANNOTATIONS))) return originalAnnotationArray;
-		return addAnnotation(source, originalAnnotationArray, LOMBOK_CHECK_RETURN_VALUE);
+		CheckReturnValueFlavor flavor = node.getAst().readConfiguration(ConfigurationKeys.CHECK_RETURN_VALUE_ANNOTATION);
+		if (flavor == null) flavor = CheckReturnValueFlavor.NONE;
+		switch (flavor) {
+		case LOMBOK:
+			return addAnnotation(source, originalAnnotationArray, LOMBOK_CHECK_RETURN_VALUE);
+		case NONE:
+		default:
+			return originalAnnotationArray;
+		}
 	}
 
 	static Annotation[] addAnnotation(ASTNode source, Annotation[] originalAnnotationArray, char[][] annotationTypeFqn) {

src/core/lombok/javac/handlers/JavacHandlerUtil.java

@@ -96,6 +96,7 @@ import lombok.core.AnnotationValues.AnnotationValue;
 import lombok.core.CleanupTask;
 import lombok.core.LombokImmutableList;
 import lombok.core.TypeResolver;
+import lombok.core.configuration.CheckReturnValueFlavor;
 import lombok.core.configuration.CheckerFrameworkVersion;
 import lombok.core.configuration.NullAnnotationLibrary;
 import lombok.core.configuration.NullCheckExceptionType;
@@ -1555,8 +1556,16 @@ public class JavacHandlerUtil {
 	}
 	
 	public static void addCheckReturnValue(JCModifiers mods, JavacNode node, JavacNode source) {
-		if (!Boolean.TRUE.equals(node.getAst().readConfiguration(ConfigurationKeys.ADD_CHECK_RETURN_VALUE_ANNOTATIONS))) return;
-		addAnnotation(mods, node, source, "lombok.CheckReturnValue", null);
+		CheckReturnValueFlavor flavor = node.getAst().readConfiguration(ConfigurationKeys.CHECK_RETURN_VALUE_ANNOTATION);
+		if (flavor == null) flavor = CheckReturnValueFlavor.NONE;
+		switch (flavor) {
+		case LOMBOK:
+			addAnnotation(mods, node, source, "lombok.CheckReturnValue", null);
+			return;
+		case NONE:
+		default:
+			return;
+		}
 	}
 
 	public static void addAnnotation(JCModifiers mods, JavacNode node, JavacNode source, String annotationTypeFqn, JCExpression arg) {

test/transform/resource/before/CheckReturnValueBuilder.java

@@ -1,4 +1,4 @@
-//CONF: lombok.addCheckReturnValueAnnotation = true
+//CONF: lombok.checkReturnValueAnnotation = lombok
 @lombok.Builder
 class CheckReturnValueBuilder {
 	private final int x;

test/transform/resource/before/CheckReturnValueOff.java

@@ -1,4 +1,4 @@
-//CONF: lombok.addCheckReturnValueAnnotation = false
+//CONF: lombok.checkReturnValueAnnotation = none
 import lombok.With;
 class CheckReturnValueOff {
 	@With final int x;

test/transform/resource/before/CheckReturnValueWith.java

@@ -1,4 +1,4 @@
-//CONF: lombok.addCheckReturnValueAnnotation = true
+//CONF: lombok.checkReturnValueAnnotation = lombok
 import lombok.With;
 class CheckReturnValueWith {
 	@With final int x;

website/templates/features/configuration.html

@@ -89,6 +89,12 @@
 			</ol>
 			Many <em>flavors</em> are available: <code>jspecify</code> (recommended), <code>checkerframework</code> (recommended), <code>jakarta</code>, <code>eclipse</code>, <code>jetbrains</code>, <code>netbeans</code>, <code>androidx</code>, <code>findbugs</code>, <code>spring</code>, <code>jml</code>, <code>javax</code> (=JSR305; not recommended), <code>android.support</code> (deprecated within android), or define your own via <code>CUSTOM:fully.qualified.NonNullAnnotation:fully.qualified.NullableAnnotation</code>; 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 <code>CUSTOM:TYPE_USE:nonnullanno:nullableanno</code>.<br />
 			<em>This feature was added in lombok v1.18.12</em>.<br />
+		</p><p id="checkReturnValueAnnotation">
+			Lombok can add a <code>@CheckReturnValue</code> annotation to generated methods whose return value should not be ignored, such as <a href="with"><code>withX</code></a> methods and <a href="Builder"><code>@Builder</code></a>'s <code>build()</code> 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:
+			<ol class="snippet example oneliner">
+				<li><code>lombok.checkReturnValueAnnotation = <em>&lt;flavor&gt;</em></code></li>
+			</ol>
+			Currently the only non-<code>none</code> flavor is <code>lombok</code>, which emits <code>@lombok.CheckReturnValue</code>. A future lombok release may flip the default to <code>lombok</code>.<br />
 		</p><p>
 			Lombok can be configured to add <code>@lombok.Generated</code> annotations to all generated nodes where possible; useful for JaCoCo (which has built in support),
 			or other style checkers and code coverage tools: