[With] renaming lombok.experimental.Wither to lombok.experimental.With

9 files changed, 219 insertions, 116 deletions

diff --git a/src/core/lombok/ConfigurationKeys.java b/src/core/lombok/ConfigurationKeys.java
index d46889d6..0baf1f3b 100644
--- a/src/core/lombok/ConfigurationKeys.java
+++ b/src/core/lombok/ConfigurationKeys.java
@@ -593,14 +593,14 @@ public class ConfigurationKeys {
 	 */
 	public static final ConfigurationKey<Boolean> FIELD_NAME_CONSTANTS_UPPERCASE = new ConfigurationKey<Boolean>("lombok.fieldNameConstants.uppercase", "The default name of the constants inside the inner type generated by @FieldNameConstants follow the variable name precisely. If this config key is true, lombok will uppercase them as best it can. (default: false).") {};
 	
-	// ----- Wither -----
+	// ----- With -----
 	
 	/**
-	 * lombok configuration: {@code lombok.wither.flagUsage} = {@code WARNING} | {@code ERROR}.
+	 * lombok configuration: {@code lombok.with.flagUsage} = {@code WARNING} | {@code ERROR}.
 	 * 
-	 * If set, <em>any</em> usage of {@code @Wither} results in a warning / error.
+	 * If set, <em>any</em> usage of {@code @With} results in a warning / error.
 	 */
-	public static final ConfigurationKey<FlagUsageType> WITHER_FLAG_USAGE = new ConfigurationKey<FlagUsageType>("lombok.wither.flagUsage", "Emit a warning or error if @Wither is used.") {};
+	public static final ConfigurationKey<FlagUsageType> WITH_FLAG_USAGE = new ConfigurationKey<FlagUsageType>("lombok.with.flagUsage", "Emit a warning or error if @With is used.") {};
 	
 	// ----- SuperBuilder -----
 	
@@ -625,9 +625,9 @@ public class ConfigurationKeys {
 	/**
 	 * lombok configuration: {@code lombok.copyableAnnotations} += &lt;TypeName: fully-qualified annotation class name&gt;.
 	 *
-	 * Copy these annotations to getters, setters, withers, builder-setters, etc.
+	 * Copy these annotations to getters, setters, with methods, builder-setters, etc.
 	 */
-	public static final ConfigurationKey<List<TypeName>> COPYABLE_ANNOTATIONS = new ConfigurationKey<List<TypeName>>("lombok.copyableAnnotations", "Copy these annotations to getters, setters, withers, builder-setters, etc.") {};
+	public static final ConfigurationKey<List<TypeName>> COPYABLE_ANNOTATIONS = new ConfigurationKey<List<TypeName>>("lombok.copyableAnnotations", "Copy these annotations to getters, setters, with methods, builder-setters, etc.") {};
 	
 	/**
 	 * lombok configuration: {@code checkerframework} = {@code true} | {@code false} | &lt;String: MajorVer.MinorVer&gt; (Default: false).
diff --git a/src/core/lombok/With.java b/src/core/lombok/With.java
new file mode 100644
index 00000000..141d1fa6
--- /dev/null
+++ b/src/core/lombok/With.java
@@ -0,0 +1,94 @@
+/*
+ * Copyright (C) 2012-2019 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;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import lombok.AccessLevel;
+
+/**
+ * Put on any field to make lombok build a 'with' - a withX method which produces a clone of this object (except for 1 field which gets a new value).
+ * <p>
+ * Complete documentation is found at <a href="https://projectlombok.org/features/With">the project lombok features page for &#64;With</a>.
+ * <p>
+ * Example:
+ * <pre>
+ *     private &#64;With final int foo;
+ * </pre>
+ * 
+ * will generate:
+ * 
+ * <pre>
+ *     public SELF_TYPE withFoo(int foo) {
+ *         return this.foo == foo ? this : new SELF_TYPE(otherField1, otherField2, foo);
+ *     }
+ * </pre>
+ * <p>
+ * This annotation can also be applied to a class, in which case it'll be as if all non-static fields that don't already have
+ * a {@code With} annotation have the annotation.
+ */
+@Target({ElementType.FIELD, ElementType.TYPE})
+@Retention(RetentionPolicy.SOURCE)
+public @interface With {
+	/**
+	 * If you want your with method to be non-public, you can specify an alternate access level here.
+	 * 
+	 * @return The method will be generated with this access modifier.
+	 */
+	AccessLevel value() default AccessLevel.PUBLIC;
+	
+	/**
+	 * Any annotations listed here are put on the generated method.
+	 * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br>
+	 * up to JDK7:<br>
+	 *  {@code @With(onMethod=@__({@AnnotationsGoHere}))}<br>
+	 * from JDK8:<br>
+	 *  {@code @With(onMethod_={@AnnotationsGohere})} // note the underscore after {@code onMethod}.
+	 * 
+	 * @return List of annotations to apply to the generated method.
+	 */
+	AnyAnnotation[] onMethod() default {};
+	
+	/**
+	 * Any annotations listed here are put on the generated method's parameter.
+	 * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br>
+	 * up to JDK7:<br>
+	 *  {@code @With(onParam=@__({@AnnotationsGoHere}))}<br>
+	 * from JDK8:<br>
+	 *  {@code @With(onParam_={@AnnotationsGohere})} // note the underscore after {@code onParam}.
+	 * 
+	 * @return List of annotations to apply to the generated parameter in the method.
+	 */
+	AnyAnnotation[] onParam() default {};
+	
+	/**
+	  * Placeholder annotation to enable the placement of annotations on the generated code.
+	  * @deprecated Don't use this annotation, ever - Read the documentation.
+	  */
+	@Deprecated
+	@Retention(RetentionPolicy.SOURCE)
+	@Target({})
+	@interface AnyAnnotation {}
+}
diff --git a/src/core/lombok/core/LombokInternalAliasing.java b/src/core/lombok/core/LombokInternalAliasing.java
index c1089580..0b92d3b9 100644
--- a/src/core/lombok/core/LombokInternalAliasing.java
+++ b/src/core/lombok/core/LombokInternalAliasing.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2013-2018 The Project Lombok Authors.
+ * Copyright (C) 2013-2019 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
@@ -51,6 +51,7 @@ public class LombokInternalAliasing {
 		m2.put("lombok.experimental.Builder", "lombok.Builder");
 		m2.put("lombok.experimental.var", "lombok.var");
 		m2.put("lombok.Delegate", "lombok.experimental.Delegate");
+		m2.put("lombok.experimental.Wither", "lombok.With");
 		ALIASES = Collections.unmodifiableMap(m2);
 	}
 }
diff --git a/src/core/lombok/core/handlers/HandlerUtil.java b/src/core/lombok/core/handlers/HandlerUtil.java
index 21a3a216..be32e101 100644
--- a/src/core/lombok/core/handlers/HandlerUtil.java
+++ b/src/core/lombok/core/handlers/HandlerUtil.java
@@ -38,6 +38,7 @@ import lombok.RequiredArgsConstructor;
 import lombok.Setter;
 import lombok.ToString;
 import lombok.Value;
+import lombok.With;
 import lombok.core.AST;
 import lombok.core.AnnotationValues;
 import lombok.core.JavaIdentifiers;
@@ -47,7 +48,6 @@ import lombok.core.configuration.ConfigurationKey;
 import lombok.core.configuration.FlagUsageType;
 import lombok.experimental.Accessors;
 import lombok.experimental.FieldDefaults;
-import lombok.experimental.Wither;
 
 /**
  * Container for static utility methods useful for some of the standard lombok handlers, regardless of
@@ -406,7 +406,7 @@ public class HandlerUtil {
 	@SuppressWarnings({"all", "unchecked", "deprecation"})
 	public static final List<String> INVALID_ON_BUILDERS = Collections.unmodifiableList(
 			Arrays.<String>asList(
-			Getter.class.getName(), Setter.class.getName(), Wither.class.getName(),
+			Getter.class.getName(), Setter.class.getName(), With.class.getName(), "lombok.experimental.Wither",
 			ToString.class.getName(), EqualsAndHashCode.class.getName(), 
 			RequiredArgsConstructor.class.getName(), AllArgsConstructor.class.getName(), NoArgsConstructor.class.getName(), 
 			Data.class.getName(), Value.class.getName(), "lombok.experimental.Value", FieldDefaults.class.getName()));
@@ -502,7 +502,7 @@ public class HandlerUtil {
 	}
 	
 	/**
-	 * Generates a wither name from a given field name.
+	 * Generates a with name from a given field name.
 	 * 
 	 * Strategy:
 	 * <ul>
@@ -518,9 +518,9 @@ public class HandlerUtil {
 	 * @param accessors Accessors configuration.
 	 * @param fieldName the name of the field.
 	 * @param isBoolean if the field is of type 'boolean'. For fields of type {@code java.lang.Boolean}, you should provide {@code false}.
-	 * @return The wither name for this field, or {@code null} if this field does not fit expected patterns and therefore cannot be turned into a getter name.
+	 * @return The with name for this field, or {@code null} if this field does not fit expected patterns and therefore cannot be turned into a getter name.
 	 */
-	public static String toWitherName(AST<?, ?, ?> ast, AnnotationValues<Accessors> accessors, CharSequence fieldName, boolean isBoolean) {
+	public static String toWithName(AST<?, ?, ?> ast, AnnotationValues<Accessors> accessors, CharSequence fieldName, boolean isBoolean) {
 		return toAccessorName(ast, accessors, fieldName, isBoolean, "with", "with", false);
 	}
 	
@@ -582,7 +582,7 @@ public class HandlerUtil {
 	}
 	
 	/**
-	 * Returns all names of methods that would represent the wither for a field with the provided name.
+	 * Returns all names of methods that would represent the with for a field with the provided name.
 	 * 
 	 * For example if {@code isBoolean} is true, then a field named {@code isRunning} would produce:<br />
 	 * {@code [withRunning, withIsRunning]}
@@ -591,7 +591,7 @@ public class HandlerUtil {
 	 * @param fieldName the name of the field.
 	 * @param isBoolean if the field is of type 'boolean'. For fields of type 'java.lang.Boolean', you should provide {@code false}.
 	 */
-	public static List<String> toAllWitherNames(AST<?, ?, ?> ast, AnnotationValues<Accessors> accessors, CharSequence fieldName, boolean isBoolean) {
+	public static List<String> toAllWithNames(AST<?, ?, ?> ast, AnnotationValues<Accessors> accessors, CharSequence fieldName, boolean isBoolean) {
 		return toAllAccessorNames(ast, accessors, fieldName, isBoolean, "with", "with", false);
 	}
 	
diff --git a/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java b/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java
index 6a6d4cca..0955dba6 100644
--- a/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java
+++ b/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java
@@ -1417,20 +1417,20 @@ public class EclipseHandlerUtil {
 	}
 	
 	/**
-	 * Translates the given field into all possible wither names.
-	 * Convenient wrapper around {@link TransformationsUtil#toAllWitherNames(lombok.core.AnnotationValues, CharSequence, boolean)}.
+	 * Translates the given field into all possible with names.
+	 * Convenient wrapper around {@link TransformationsUtil#toAllWithNames(lombok.core.AnnotationValues, CharSequence, boolean)}.
 	 */
-	public static java.util.List<String> toAllWitherNames(EclipseNode field, boolean isBoolean) {
-		return HandlerUtil.toAllWitherNames(field.getAst(), getAccessorsForField(field), field.getName(), isBoolean);
+	public static java.util.List<String> toAllWithNames(EclipseNode field, boolean isBoolean) {
+		return HandlerUtil.toAllWithNames(field.getAst(), getAccessorsForField(field), field.getName(), isBoolean);
 	}
 	
 	/**
-	 * @return the likely wither name for the stated field. (e.g. private boolean foo; to withFoo).
+	 * @return the likely with name for the stated field. (e.g. private boolean foo; to withFoo).
 	 * 
-	 * Convenient wrapper around {@link TransformationsUtil#toWitherName(lombok.core.AnnotationValues, CharSequence, boolean)}.
+	 * Convenient wrapper around {@link TransformationsUtil#toWithName(lombok.core.AnnotationValues, CharSequence, boolean)}.
 	 */
-	public static String toWitherName(EclipseNode field, boolean isBoolean) {
-		return HandlerUtil.toWitherName(field.getAst(), getAccessorsForField(field), field.getName(), isBoolean);
+	public static String toWithName(EclipseNode field, boolean isBoolean) {
+		return HandlerUtil.toWithName(field.getAst(), getAccessorsForField(field), field.getName(), isBoolean);
 	}
 	
 	/**
diff --git a/src/core/lombok/eclipse/handlers/HandleWither.java b/src/core/lombok/eclipse/handlers/HandleWith.java
index 8be08cfe..8c8c3712 100644
--- a/src/core/lombok/eclipse/handlers/HandleWither.java
+++ b/src/core/lombok/eclipse/handlers/HandleWith.java
@@ -32,12 +32,12 @@ import java.util.List;
 
 import lombok.AccessLevel;
 import lombok.ConfigurationKeys;
+import lombok.With;
 import lombok.core.AST.Kind;
 import lombok.core.configuration.CheckerFrameworkVersion;
 import lombok.core.AnnotationValues;
 import lombok.eclipse.EclipseAnnotationHandler;
 import lombok.eclipse.EclipseNode;
-import lombok.experimental.Wither;
 
 import org.eclipse.jdt.internal.compiler.ast.ASTNode;
 import org.eclipse.jdt.internal.compiler.ast.AllocationExpression;
@@ -60,10 +60,10 @@ import org.eclipse.jdt.internal.compiler.lookup.ExtraCompilerModifiers;
 import org.mangosdk.spi.ProviderFor;
 
 @ProviderFor(EclipseAnnotationHandler.class)
-public class HandleWither extends EclipseAnnotationHandler<Wither> {
-	public boolean generateWitherForType(EclipseNode typeNode, EclipseNode pos, AccessLevel level, boolean checkForTypeLevelWither) {
-		if (checkForTypeLevelWither) {
-			if (hasAnnotation(Wither.class, typeNode)) {
+public class HandleWith extends EclipseAnnotationHandler<With> {
+	public boolean generateWithForType(EclipseNode typeNode, EclipseNode pos, AccessLevel level, boolean checkForTypeLevelWith) {
+		if (checkForTypeLevelWith) {
+			if (hasAnnotation(With.class, typeNode)) {
 				//The annotation will make it happen, so we can skip it.
 				return true;
 			}
@@ -76,7 +76,7 @@ public class HandleWither extends EclipseAnnotationHandler<Wither> {
 				(ClassFileConstants.AccInterface | ClassFileConstants.AccAnnotation | ClassFileConstants.AccEnum)) != 0;
 		
 		if (typeDecl == null || notAClass) {
-			pos.addError("@Wither is only supported on a class or a field.");
+			pos.addError("@With is only supported on a class or a field.");
 			return false;
 		}
 		
@@ -88,28 +88,28 @@ public class HandleWither extends EclipseAnnotationHandler<Wither> {
 			//Skip final fields.
 			if ((fieldDecl.modifiers & ClassFileConstants.AccFinal) != 0 && fieldDecl.initialization != null) continue;
 			
-			generateWitherForField(field, pos, level);
+			generateWithForField(field, pos, level);
 		}
 		return true;
 	}
 	
 	
 	/**
-	 * Generates a wither on the stated field.
+	 * Generates a with on the stated field.
 	 * 
 	 * Used by {@link HandleValue}.
 	 * 
 	 * The difference between this call and the handle method is as follows:
 	 * 
-	 * If there is a {@code lombok.experimental.Wither} annotation on the field, it is used and the
+	 * If there is a {@code lombok.With} annotation on the field, it is used and the
 	 * same rules apply (e.g. warning if the method already exists, stated access level applies).
-	 * If not, the wither is still generated if it isn't already there, though there will not
+	 * If not, the with method is still generated if it isn't already there, though there will not
 	 * be a warning if its already there. The default access level is used.
 	 */
-	public void generateWitherForField(EclipseNode fieldNode, EclipseNode sourceNode, AccessLevel level) {
+	public void generateWithForField(EclipseNode fieldNode, EclipseNode sourceNode, AccessLevel level) {
 		for (EclipseNode child : fieldNode.down()) {
 			if (child.getKind() == Kind.ANNOTATION) {
-				if (annotationTypeMatches(Wither.class, child)) {
+				if (annotationTypeMatches(With.class, child)) {
 					//The annotation will make it happen, so we can skip it.
 					return;
 				}
@@ -117,49 +117,49 @@ public class HandleWither extends EclipseAnnotationHandler<Wither> {
 		}
 		
 		List<Annotation> empty = Collections.emptyList();
-		createWitherForField(level, fieldNode, sourceNode, false, empty, empty);
+		createWithForField(level, fieldNode, sourceNode, false, empty, empty);
 	}
 	
-	@Override public void handle(AnnotationValues<Wither> annotation, Annotation ast, EclipseNode annotationNode) {
-		handleExperimentalFlagUsage(annotationNode, ConfigurationKeys.WITHER_FLAG_USAGE, "@Wither");
+	@Override public void handle(AnnotationValues<With> annotation, Annotation ast, EclipseNode annotationNode) {
+		handleExperimentalFlagUsage(annotationNode, ConfigurationKeys.WITH_FLAG_USAGE, "@With");
 		
 		EclipseNode node = annotationNode.up();
 		AccessLevel level = annotation.getInstance().value();
 		if (level == AccessLevel.NONE || node == null) return;
 		
-		List<Annotation> onMethod = unboxAndRemoveAnnotationParameter(ast, "onMethod", "@Wither(onMethod", annotationNode);
-		List<Annotation> onParam = unboxAndRemoveAnnotationParameter(ast, "onParam", "@Wither(onParam", annotationNode);
+		List<Annotation> onMethod = unboxAndRemoveAnnotationParameter(ast, "onMethod", "@With(onMethod", annotationNode);
+		List<Annotation> onParam = unboxAndRemoveAnnotationParameter(ast, "onParam", "@With(onParam", annotationNode);
 		
 		switch (node.getKind()) {
 		case FIELD:
-			createWitherForFields(level, annotationNode.upFromAnnotationToFields(), annotationNode, true, onMethod, onParam);
+			createWithForFields(level, annotationNode.upFromAnnotationToFields(), annotationNode, true, onMethod, onParam);
 			break;
 		case TYPE:
 			if (!onMethod.isEmpty()) {
-				annotationNode.addError("'onMethod' is not supported for @Wither on a type.");
+				annotationNode.addError("'onMethod' is not supported for @With on a type.");
 			}
 			if (!onParam.isEmpty()) {
-				annotationNode.addError("'onParam' is not supported for @Wither on a type.");
+				annotationNode.addError("'onParam' is not supported for @With on a type.");
 			}
-			generateWitherForType(node, annotationNode, level, false);
+			generateWithForType(node, annotationNode, level, false);
 			break;
 		}
 	}
 	
-	public void createWitherForFields(AccessLevel level, Collection<EclipseNode> fieldNodes, EclipseNode sourceNode, boolean whineIfExists, List<Annotation> onMethod, List<Annotation> onParam) {
+	public void createWithForFields(AccessLevel level, Collection<EclipseNode> fieldNodes, EclipseNode sourceNode, boolean whineIfExists, List<Annotation> onMethod, List<Annotation> onParam) {
 		for (EclipseNode fieldNode : fieldNodes) {
-			createWitherForField(level, fieldNode, sourceNode, whineIfExists, onMethod, onParam);
+			createWithForField(level, fieldNode, sourceNode, whineIfExists, onMethod, onParam);
 		}
 	}
 	
-	public void createWitherForField(
+	public void createWithForField(
 			AccessLevel level, EclipseNode fieldNode, EclipseNode sourceNode,
 			boolean whineIfExists, List<Annotation> onMethod,
 			List<Annotation> onParam) {
 		
 		ASTNode source = sourceNode.get();
 		if (fieldNode.getKind() != Kind.FIELD) {
-			sourceNode.addError("@Wither is only supported on a class or a field.");
+			sourceNode.addError("@With is only supported on a class or a field.");
 			return;
 		}
 		
@@ -169,38 +169,38 @@ public class HandleWither extends EclipseAnnotationHandler<Wither> {
 		FieldDeclaration field = (FieldDeclaration) fieldNode.get();
 		TypeReference fieldType = copyType(field.type, source);
 		boolean isBoolean = isBoolean(fieldType);
-		String witherName = toWitherName(fieldNode, isBoolean);
+		String withName = toWithName(fieldNode, isBoolean);
 		
-		if (witherName == null) {
-			fieldNode.addWarning("Not generating wither for this field: It does not fit your @Accessors prefix list.");
+		if (withName == null) {
+			fieldNode.addWarning("Not generating a with method for this field: It does not fit your @Accessors prefix list.");
 			return;
 		}
 		
 		if ((field.modifiers & ClassFileConstants.AccStatic) != 0) {
-			fieldNode.addWarning("Not generating wither for this field: Withers cannot be generated for static fields.");
+			fieldNode.addWarning("Not generating " + withName + " for this field: With methods cannot be generated for static fields.");
 			return;
 		}
 		
 		if ((field.modifiers & ClassFileConstants.AccFinal) != 0 && field.initialization != null) {
-			fieldNode.addWarning("Not generating wither for this field: Withers cannot be generated for final, initialized fields.");
+			fieldNode.addWarning("Not generating " + withName + " for this field: With methods cannot be generated for final, initialized fields.");
 			return;
 		}
 		
 		if (field.name != null && field.name.length > 0 && field.name[0] == '$') {
-			fieldNode.addWarning("Not generating wither for this field: Withers cannot be generated for fields starting with $.");
+			fieldNode.addWarning("Not generating " + withName + " for this field: With methods cannot be generated for fields starting with $.");
 			return;
 		}
 		
-		for (String altName : toAllWitherNames(fieldNode, isBoolean)) {
+		for (String altName : toAllWithNames(fieldNode, isBoolean)) {
 			switch (methodExists(altName, fieldNode, false, 1)) {
 			case EXISTS_BY_LOMBOK:
 				return;
 			case EXISTS_BY_USER:
 				if (whineIfExists) {
 					String altNameExpl = "";
-					if (!altName.equals(witherName)) altNameExpl = String.format(" (%s)", altName);
+					if (!altName.equals(withName)) altNameExpl = String.format(" (%s)", altName);
 					fieldNode.addWarning(
-						String.format("Not generating %s(): A method with that name already exists%s", witherName, altNameExpl));
+						String.format("Not generating %s(): A method with that name already exists%s", withName, altNameExpl));
 				}
 				return;
 			default:
@@ -211,11 +211,11 @@ public class HandleWither extends EclipseAnnotationHandler<Wither> {
 		
 		int modifier = toEclipseModifier(level);
 		
-		MethodDeclaration method = createWither((TypeDeclaration) fieldNode.up().get(), fieldNode, witherName, modifier, sourceNode, onMethod, onParam, makeAbstract);
+		MethodDeclaration method = createWith((TypeDeclaration) fieldNode.up().get(), fieldNode, withName, modifier, sourceNode, onMethod, onParam, makeAbstract);
 		injectMethod(fieldNode.up(), method);
 	}
 	
-	public MethodDeclaration createWither(TypeDeclaration parent, EclipseNode fieldNode, String name, int modifier, EclipseNode sourceNode, List<Annotation> onMethod, List<Annotation> onParam, boolean makeAbstract ) {
+	public MethodDeclaration createWith(TypeDeclaration parent, EclipseNode fieldNode, String name, int modifier, EclipseNode sourceNode, List<Annotation> onMethod, List<Annotation> onParam, boolean makeAbstract ) {
 		ASTNode source = sourceNode.get();
 		if (name == null) return null;
 		FieldDeclaration field = (FieldDeclaration) fieldNode.get();
diff --git a/src/core/lombok/experimental/Wither.java b/src/core/lombok/experimental/Wither.java
index 3df546d0..cf20c1eb 100644
--- a/src/core/lombok/experimental/Wither.java
+++ b/src/core/lombok/experimental/Wither.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2012-2017 The Project Lombok Authors.
+ * Copyright (C) 2012-2019 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
@@ -50,6 +50,8 @@ import lombok.AccessLevel;
  * <p>
  * This annotation can also be applied to a class, in which case it'll be as if all non-static fields that don't already have
  * a {@code Wither} annotation have the annotation.
+ * 
+ * @deprecated {@link lombok.With} has been promoted to the main package, so use that one instead.
  */
 @Target({ElementType.FIELD, ElementType.TYPE})
 @Retention(RetentionPolicy.SOURCE)
diff --git a/src/core/lombok/javac/handlers/HandleWither.java b/src/core/lombok/javac/handlers/HandleWith.java
index 9c95cb78..fd14e06a 100644
--- a/src/core/lombok/javac/handlers/HandleWither.java
+++ b/src/core/lombok/javac/handlers/HandleWith.java
@@ -29,10 +29,10 @@ import java.util.Collection;
 
 import lombok.AccessLevel;
 import lombok.ConfigurationKeys;
+import lombok.With;
 import lombok.core.AST.Kind;
 import lombok.core.AnnotationValues;
 import lombok.core.configuration.CheckerFrameworkVersion;
-import lombok.experimental.Wither;
 import lombok.javac.JavacAnnotationHandler;
 import lombok.javac.JavacNode;
 import lombok.javac.JavacTreeMaker;
@@ -60,13 +60,13 @@ import com.sun.tools.javac.util.ListBuffer;
 import com.sun.tools.javac.util.Name;
 
 /**
- * Handles the {@code lombok.experimental.Wither} annotation for javac.
+ * Handles the {@code lombok.With} annotation for javac.
  */
 @ProviderFor(JavacAnnotationHandler.class)
-public class HandleWither extends JavacAnnotationHandler<Wither> {
-	public void generateWitherForType(JavacNode typeNode, JavacNode errorNode, AccessLevel level, boolean checkForTypeLevelWither) {
-		if (checkForTypeLevelWither) {
-			if (hasAnnotation(Wither.class, typeNode)) {
+public class HandleWith extends JavacAnnotationHandler<With> {
+	public void generateWithForType(JavacNode typeNode, JavacNode errorNode, AccessLevel level, boolean checkForTypeLevelWith) {
+		if (checkForTypeLevelWith) {
+			if (hasAnnotation(With.class, typeNode)) {
 				//The annotation will make it happen, so we can skip it.
 				return;
 			}
@@ -78,7 +78,7 @@ public class HandleWither extends JavacAnnotationHandler<Wither> {
 		boolean notAClass = (modifiers & (Flags.INTERFACE | Flags.ANNOTATION | Flags.ENUM)) != 0;
 		
 		if (typeDecl == null || notAClass) {
-			errorNode.addError("@Wither is only supported on a class or a field.");
+			errorNode.addError("@With is only supported on a class or a field.");
 			return;
 		}
 		
@@ -92,105 +92,105 @@ public class HandleWither extends JavacAnnotationHandler<Wither> {
 			//Skip final initialized fields.
 			if ((fieldDecl.mods.flags & Flags.FINAL) != 0 && fieldDecl.init != null) continue;
 			
-			generateWitherForField(field, errorNode.get(), level);
+			generateWithForField(field, errorNode.get(), level);
 		}
 	}
 	
 	/**
-	 * Generates a wither on the stated field.
+	 * Generates a with on the stated field.
 	 * 
 	 * Used by {@link HandleValue}.
 	 * 
 	 * The difference between this call and the handle method is as follows:
 	 * 
-	 * If there is a {@code lombok.experimental.Wither} annotation on the field, it is used and the
+	 * If there is a {@code lombok.experimental.With} annotation on the field, it is used and the
 	 * same rules apply (e.g. warning if the method already exists, stated access level applies).
-	 * If not, the wither is still generated if it isn't already there, though there will not
+	 * If not, the with is still generated if it isn't already there, though there will not
 	 * be a warning if its already there. The default access level is used.
 	 * 
-	 * @param fieldNode The node representing the field you want a wither for.
-	 * @param pos The node responsible for generating the wither (the {@code @Value} or {@code @Wither} annotation).
+	 * @param fieldNode The node representing the field you want a with for.
+	 * @param pos The node responsible for generating the with (the {@code @Value} or {@code @With} annotation).
 	 */
-	public void generateWitherForField(JavacNode fieldNode, DiagnosticPosition pos, AccessLevel level) {
-		if (hasAnnotation(Wither.class, fieldNode)) {
+	public void generateWithForField(JavacNode fieldNode, DiagnosticPosition pos, AccessLevel level) {
+		if (hasAnnotation(With.class, fieldNode)) {
 			//The annotation will make it happen, so we can skip it.
 			return;
 		}
 		
-		createWitherForField(level, fieldNode, fieldNode, false, List.<JCAnnotation>nil(), List.<JCAnnotation>nil());
+		createWithForField(level, fieldNode, fieldNode, false, List.<JCAnnotation>nil(), List.<JCAnnotation>nil());
 	}
 	
-	@Override public void handle(AnnotationValues<Wither> annotation, JCAnnotation ast, JavacNode annotationNode) {
-		handleExperimentalFlagUsage(annotationNode, ConfigurationKeys.WITHER_FLAG_USAGE, "@Wither");
+	@Override public void handle(AnnotationValues<With> annotation, JCAnnotation ast, JavacNode annotationNode) {
+		handleFlagUsage(annotationNode, ConfigurationKeys.WITH_FLAG_USAGE, "@With");
 		
 		Collection<JavacNode> fields = annotationNode.upFromAnnotationToFields();
-		deleteAnnotationIfNeccessary(annotationNode, Wither.class);
+		deleteAnnotationIfNeccessary(annotationNode, With.class, "lombok.experimental.Wither");
 		deleteImportFromCompilationUnit(annotationNode, "lombok.AccessLevel");
 		JavacNode node = annotationNode.up();
 		AccessLevel level = annotation.getInstance().value();
 		
 		if (level == AccessLevel.NONE || node == null) return;
 		
-		List<JCAnnotation> onMethod = unboxAndRemoveAnnotationParameter(ast, "onMethod", "@Wither(onMethod", annotationNode);
-		List<JCAnnotation> onParam = unboxAndRemoveAnnotationParameter(ast, "onParam", "@Wither(onParam", annotationNode);
+		List<JCAnnotation> onMethod = unboxAndRemoveAnnotationParameter(ast, "onMethod", "@With(onMethod", annotationNode);
+		List<JCAnnotation> onParam = unboxAndRemoveAnnotationParameter(ast, "onParam", "@With(onParam", annotationNode);
 		
 		switch (node.getKind()) {
 		case FIELD:
-			createWitherForFields(level, fields, annotationNode, true, onMethod, onParam);
+			createWithForFields(level, fields, annotationNode, true, onMethod, onParam);
 			break;
 		case TYPE:
-			if (!onMethod.isEmpty()) annotationNode.addError("'onMethod' is not supported for @Wither on a type.");
-			if (!onParam.isEmpty()) annotationNode.addError("'onParam' is not supported for @Wither on a type.");
-			generateWitherForType(node, annotationNode, level, false);
+			if (!onMethod.isEmpty()) annotationNode.addError("'onMethod' is not supported for @With on a type.");
+			if (!onParam.isEmpty()) annotationNode.addError("'onParam' is not supported for @With on a type.");
+			generateWithForType(node, annotationNode, level, false);
 			break;
 		}
 	}
 	
-	public void createWitherForFields(AccessLevel level, Collection<JavacNode> fieldNodes, JavacNode errorNode, boolean whineIfExists, List<JCAnnotation> onMethod, List<JCAnnotation> onParam) {
+	public void createWithForFields(AccessLevel level, Collection<JavacNode> fieldNodes, JavacNode errorNode, boolean whineIfExists, List<JCAnnotation> onMethod, List<JCAnnotation> onParam) {
 		for (JavacNode fieldNode : fieldNodes) {
-			createWitherForField(level, fieldNode, errorNode, whineIfExists, onMethod, onParam);
+			createWithForField(level, fieldNode, errorNode, whineIfExists, onMethod, onParam);
 		}
 	}
 	
-	public void createWitherForField(AccessLevel level, JavacNode fieldNode, JavacNode source, boolean strictMode, List<JCAnnotation> onMethod, List<JCAnnotation> onParam) {
+	public void createWithForField(AccessLevel level, JavacNode fieldNode, JavacNode source, boolean strictMode, List<JCAnnotation> onMethod, List<JCAnnotation> onParam) {
 		JavacNode typeNode = fieldNode.up();
 		boolean makeAbstract = typeNode != null && typeNode.getKind() == Kind.TYPE && (((JCClassDecl) typeNode.get()).mods.flags & Flags.ABSTRACT) != 0;
 		
 		if (fieldNode.getKind() != Kind.FIELD) {
-			fieldNode.addError("@Wither is only supported on a class or a field.");
+			fieldNode.addError("@With is only supported on a class or a field.");
 			return;
 		}
 		
-		JCVariableDecl fieldDecl = (JCVariableDecl)fieldNode.get();
-		String methodName = toWitherName(fieldNode);
+		JCVariableDecl fieldDecl = (JCVariableDecl) fieldNode.get();
+		String methodName = toWithName(fieldNode);
 		
 		if (methodName == null) {
-			fieldNode.addWarning("Not generating wither for this field: It does not fit your @Accessors prefix list.");
+			fieldNode.addWarning("Not generating a withX method for this field: It does not fit your @Accessors prefix list.");
 			return;
 		}
 		
 		if ((fieldDecl.mods.flags & Flags.STATIC) != 0) {
 			if (strictMode) {
-				fieldNode.addWarning("Not generating wither for this field: Withers cannot be generated for static fields.");
+				fieldNode.addWarning("Not generating " + methodName + " for this field: With methods cannot be generated for static fields.");
 			}
 			return;
 		}
 		
 		if ((fieldDecl.mods.flags & Flags.FINAL) != 0 && fieldDecl.init != null) {
 			if (strictMode) {
-				fieldNode.addWarning("Not generating wither for this field: Withers cannot be generated for final, initialized fields.");
+				fieldNode.addWarning("Not generating " + methodName + " for this field: With methods cannot be generated for final, initialized fields.");
 			}
 			return;
 		}
 		
 		if (fieldDecl.name.toString().startsWith("$")) {
 			if (strictMode) {
-				fieldNode.addWarning("Not generating wither for this field: Withers cannot be generated for fields starting with $.");
+				fieldNode.addWarning("Not generating " + methodName + " for this field: With methods cannot be generated for fields starting with $.");
 			}
 			return;
 		}
 		
-		for (String altName : toAllWitherNames(fieldNode)) {
+		for (String altName : toAllWithNames(fieldNode)) {
 			switch (methodExists(altName, fieldNode, false, 1)) {
 			case EXISTS_BY_LOMBOK:
 				return;
@@ -210,22 +210,22 @@ public class HandleWither extends JavacAnnotationHandler<Wither> {
 		
 		long access = toJavacModifier(level);
 		
-		JCMethodDecl createdWither = createWither(access, fieldNode, fieldNode.getTreeMaker(), source, onMethod, onParam, makeAbstract);
+		JCMethodDecl createdWith = createWith(access, fieldNode, fieldNode.getTreeMaker(), source, onMethod, onParam, makeAbstract);
 		ClassSymbol sym = ((JCClassDecl) fieldNode.up().get()).sym;
 		Type returnType = sym == null ? null : sym.type;
 		
-		injectMethod(typeNode, createdWither, List.<Type>of(getMirrorForFieldType(fieldNode)), returnType);
+		injectMethod(typeNode, createdWith, List.<Type>of(getMirrorForFieldType(fieldNode)), returnType);
 	}
 	
-	public JCMethodDecl createWither(long access, JavacNode field, JavacTreeMaker maker, JavacNode source, List<JCAnnotation> onMethod, List<JCAnnotation> onParam, boolean makeAbstract) {
-		String witherName = toWitherName(field);
-		if (witherName == null) return null;
+	public JCMethodDecl createWith(long access, JavacNode field, JavacTreeMaker maker, JavacNode source, List<JCAnnotation> onMethod, List<JCAnnotation> onParam, boolean makeAbstract) {
+		String withName = toWithName(field);
+		if (withName == null) return null;
 		
 		JCVariableDecl fieldDecl = (JCVariableDecl) field.get();
 		
 		List<JCAnnotation> copyableAnnotations = findCopyableAnnotations(field);
 		
-		Name methodName = field.toName(witherName);
+		Name methodName = field.toName(withName);
 		
 		JCExpression returnType = cloneSelfType(field);
 		
@@ -287,8 +287,8 @@ public class HandleWither extends JavacAnnotationHandler<Wither> {
 		
 		if (makeAbstract) access = access | Flags.ABSTRACT;
 		JCMethodDecl decl = recursiveSetGeneratedBy(maker.MethodDef(maker.Modifiers(access, annsOnMethod), methodName, returnType,
-				methodGenericParams, parameters, throwsClauses, methodBody, annotationMethodDefaultValue), source.get(), field.getContext());
-		copyJavadoc(field, decl, CopyJavadoc.WITHER);
+			methodGenericParams, parameters, throwsClauses, methodBody, annotationMethodDefaultValue), source.get(), field.getContext());
+		copyJavadoc(field, decl, CopyJavadoc.WITH);
 		return decl;
 	}
 }
diff --git a/src/core/lombok/javac/handlers/JavacHandlerUtil.java b/src/core/lombok/javac/handlers/JavacHandlerUtil.java
index f23a894a..d12a980f 100644
--- a/src/core/lombok/javac/handlers/JavacHandlerUtil.java
+++ b/src/core/lombok/javac/handlers/JavacHandlerUtil.java
@@ -590,20 +590,20 @@ public class JavacHandlerUtil {
 	}
 	
 	/**
-	 * Translates the given field into all possible wither names.
-	 * Convenient wrapper around {@link TransformationsUtil#toAllWitherNames(lombok.core.AnnotationValues, CharSequence, boolean)}.
+	 * Translates the given field into all possible with names.
+	 * Convenient wrapper around {@link TransformationsUtil#toAllWithNames(lombok.core.AnnotationValues, CharSequence, boolean)}.
 	 */
-	public static java.util.List<String> toAllWitherNames(JavacNode field) {
-		return HandlerUtil.toAllWitherNames(field.getAst(), getAccessorsForField(field), field.getName(), isBoolean(field));
+	public static java.util.List<String> toAllWithNames(JavacNode field) {
+		return HandlerUtil.toAllWithNames(field.getAst(), getAccessorsForField(field), field.getName(), isBoolean(field));
 	}
 	
 	/**
-	 * @return the likely wither name for the stated field. (e.g. private boolean foo; to withFoo).
+	 * @return the likely with name for the stated field. (e.g. private boolean foo; to withFoo).
 	 * 
-	 * Convenient wrapper around {@link TransformationsUtil#toWitherName(lombok.core.AnnotationValues, CharSequence, boolean)}.
+	 * Convenient wrapper around {@link TransformationsUtil#toWithName(lombok.core.AnnotationValues, CharSequence, boolean)}.
 	 */
-	public static String toWitherName(JavacNode field) {
-		return HandlerUtil.toWitherName(field.getAst(), getAccessorsForField(field), field.getName(), isBoolean(field));
+	public static String toWithName(JavacNode field) {
+		return HandlerUtil.toWithName(field.getAst(), getAccessorsForField(field), field.getName(), isBoolean(field));
 	}
 	
 	/**
@@ -1883,7 +1883,7 @@ public class JavacHandlerUtil {
 		return (JCExpression) in;
 	}
 	
-	private static final Pattern SECTION_FINDER = Pattern.compile("^\\s*\\**\\s*[-*][-*]+\\s*([GS]ETTER|WITHER)\\s*[-*][-*]+\\s*\\**\\s*$", Pattern.MULTILINE | Pattern.CASE_INSENSITIVE);
+	private static final Pattern SECTION_FINDER = Pattern.compile("^\\s*\\**\\s*[-*][-*]+\\s*([GS]ETTER|WITH(?:ER)?)\\s*[-*][-*]+\\s*\\**\\s*$", Pattern.MULTILINE | Pattern.CASE_INSENSITIVE);
 	
 	public static String stripLinesWithTagFromJavadoc(String javadoc, String regexpFragment) {
 		Pattern p = Pattern.compile("^\\s*\\**\\s*" + regexpFragment + "\\s*\\**\\s*$", Pattern.MULTILINE | Pattern.CASE_INSENSITIVE);
@@ -1898,12 +1898,18 @@ public class JavacHandlerUtil {
 		return javadoc.substring(0, m.start());
 	}
 	
-	public static String getJavadocSection(String javadoc, String sectionName) {
+	public static String getJavadocSection(String javadoc, String sectionNameSpec) {
+		String[] sectionNames = sectionNameSpec.split("\\|");
 		Matcher m = SECTION_FINDER.matcher(javadoc);
 		int sectionStart = -1;
 		int sectionEnd = -1;
 		while (m.find()) {
-			if (m.group(1).equalsIgnoreCase(sectionName)) {
+			boolean found = false;
+			for (String sectionName : sectionNames) if (m.group(1).equalsIgnoreCase(sectionName)) {
+				found = true;
+				break;
+			}
+			if (found) {
 				sectionStart = m.end() + 1;
 			} else if (sectionStart != -1) {
 				sectionEnd = m.start();
@@ -1953,9 +1959,9 @@ public class JavacHandlerUtil {
 				return applySetter(cu, node, "SETTER");
 			}
 		},
-		WITHER {
+		WITH {
 			@Override public String apply(final JCCompilationUnit cu, final JavacNode node) {
-				return applySetter(cu, node, "WITHER");
+				return applySetter(cu, node, "WITH|WITHER");
 			}
 		};