Merge branch 'master' of github.com:rzwitserloot/lombok into feature/builder-setter-prefixes

3 files changed, 54 insertions, 67 deletions

diff --git a/website/templates/features/With.html b/website/templates/features/With.html
new file mode 100644
index 00000000..35c52dab
--- /dev/null
+++ b/website/templates/features/With.html
@@ -0,0 +1,53 @@
+<#import "_features.html" as f>
+
+<@f.scaffold title="@With" logline="Immutable 'setters' - methods that create a clone but with one changed field.">
+	<@f.history>
+		<p>
+			<code>@Wither</code> was introduced as experimental feature in lombok v0.11.4.
+		</p><p>
+			<code>@Wither</code> was renamed to <code>@With</code>, and moved out of experimental and into the core package, in lombok v1.18.10.
+	</@f.history>
+
+	<@f.overview>
+		<p>
+			The next best alternative to a setter for an immutable property is to construct a clone of the object, but with a new value for this one field. A method to generate this clone is precisely what <code>@With</code> generates: a <code>withFieldName(newValue)</code> method which produces a clone except for the new value for the associated field.
+		</p><p>
+			For example, if you create <code>public class Point { private final int x, y; }</code>, setters make no sense because the fields are final. <code>@With</code> can generate a <code>withX(int newXValue)</code> method for you which will return a new point with the supplied value for <code>x</code> and the same value for <code>y</code>.
+		</p><p>
+			Like <a href="/features/GetterSetter"><code>@Setter</code></a>, you can specify an access level in case you want the generated with method to be something other than <code>public</code>:<br /> <code>@With(level = AccessLevel.PROTECTED)</code>. Also like <a href="/features/GetterSetter"><code>@Setter</code></a>, you can also put a <code>@With</code> annotation on a type, which means a <code>with</code> method is generated for each field (even non-final fields).
+		</p><p>
+			To put annotations on the generated method, you can use <code>onMethod=@__({@AnnotationsHere})</code>. Be careful though! This is an experimental feature. For more details see the documentation on the <a href="/features/experimental/onX">onX</a> feature.
+		</p><p>
+			javadoc on the field will be copied to generated with methods. Normally, all text is copied, and <code>@param</code> is <em>moved</em> to the with method, whilst <code>@return</code> lines are stripped from the with method's javadoc. Moved means: Deleted from the field's javadoc. It is also possible to define unique text for the with method's javadoc. To do that, you create a 'section' named <code>WITH</code>. A section is a line in your javadoc containing 2 or more dashes, then the text 'WITH', followed by 2 or more dashes, and nothing else on the line. If you use sections, <code>@return</code> and <code>@param</code> stripping / copying for that section is no longer done (move the <code>@param</code> line into the section).
+		</p><p>
+			If you have a hierarchical immutable data structure, the <a href="/features/experimental/WithBy"><code>@WithBy</code></a> feature might be more suitable than <code>@With</code>
+	</@f.overview>
+
+	<@f.snippets name="With" />
+
+	<@f.confKeys>
+		<dt>
+			<code>lombok.with.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set)
+		</dt><dd>
+			Lombok will flag any usage of <code>@With</code> as a warning or error if configured.
+		</dd>
+	</@f.confKeys>
+
+	<@f.smallPrint>
+		<p>
+			With methods cannot be generated for static fields because that makes no sense.
+		</p><p>
+			With methods can be generated for abstract classes, but this generates an abstract method with the appropriate signature.
+		</p><p>
+			When applying <code>@With</code> to a type, static fields and fields whose name start with a $ are skipped.
+		</p><p>
+			For generating the method names, the first character of the field, if it is a lowercase character, is title-cased, otherwise, it is left unmodified. Then, <code>with</code> is prefixed.
+		</p><p>
+			No method is generated if any method already exists with the same name (case insensitive) and same parameter count. For example, <code>withX(int x)</code> will not be generated if there's already a method <code>withX(String... x)</code> even though it is technically possible to make the method. This caveat exists to prevent confusion. If the generation of a method is skipped for this reason, a warning is emitted instead. Varargs count as 0 to N parameters.
+		</p><p>
+			For <code>boolean</code> fields that start with <code>is</code> immediately followed by a title-case letter, nothing is prefixed to generate the wither name.
+		</p><p>
+			Various well known annotations about nullity cause null checks to be inserted and will be copied to the parameter. See <a href="/features/GetterSetter">Getter/Setter</a> documentation's small print for more information.
+		</p>
+	</@f.smallPrint>
+</@f.scaffold>
diff --git a/website/templates/features/experimental/Wither.html b/website/templates/features/experimental/Wither.html
deleted file mode 100644
index 00dc10b1..00000000
--- a/website/templates/features/experimental/Wither.html
+++ /dev/null
@@ -1,66 +0,0 @@
-<#import "../_features.html" as f>
-
-<@f.scaffold title="@Wither" logline="Immutable 'setters' - methods that create a clone but with one changed field.">
-	<@f.history>
-		<p>
-			@Wither was introduced as experimental feature in lombok v0.11.4.
-		</p>
-	</@f.history>
-
-	<@f.experimental>
-		<ul>
-			<li>
-				Still not sure that <code>@Wither</code> is an appropriate name for this feature.
-			</li><li>
-				Should there be an option to supply a way of cloning the input somehow?
-			</li><li>
-				Should the way that the clone is created by configurable?
-			</li><li>
-				Should we replace @Wither entirely with a builder class?
-			</li>
-		</ul>
-		Current status: <em>neutral</em> - More feedback requires on the items in the above list before promotion to the main package is warranted.
-	</@f.experimental>
-
-	<@f.overview>
-		<p>
-			The next best alternative to a setter for an immutable property is to construct a clone of the object, but with a new value for this one field. A method to generate this clone is precisely what <code>@Wither</code> generates: a <code>withFieldName(newValue)</code> method which produces a clone except for the new value for the associated field.
-		</p><p>
-			For example, if you create <code>public class Point { private final int x, y; }</code>, setters make no sense because the fields are final. <code>@Wither</code> can generate a <code>withX(int newXValue)</code> method for you which will return a new point with the supplied value for <code>x</code> and the same value for <code>y</code>.
-		</p><p>
-			Like <a href="/features/GetterSetter"><code>@Setter</code></a>, you can specify an access level in case you want the generated wither to be something other than <code>public</code>:<br /> <code>@Wither(level = AccessLevel.PROTECTED)</code>. Also like <a href="/features/GetterSetter"><code>@Setter</code></a>, you can also put a <code>@Wither</code> annotation on a type, which means a 'wither' is generated for each field (even non-final fields).
-		</p><p>
-			To put annotations on the generated method, you can use <code>onMethod=@__({@AnnotationsHere})</code>; to put annotations on the only parameter of a generated wither method, you can use <code>onParam=@__({@AnnotationsHere})</code>. Be careful though! This is an experimental feature. For more details see the documentation on the <a href="/features/experimental/onX">onX</a> feature.
-		</p><p>
-			<em>NEW in lombok v1.12.0:</em> javadoc on the field will now be copied to generated withers. Normally, all text is copied, and <code>@param</code> is <em>moved</em> to the wither, whilst <code>@return</code> lines are stripped from the wither's javadoc. Moved means: Deleted from the field's javadoc. It is also possible to define unique text for the wither's javadoc. To do that, you create a 'section' named <code>WITHER</code>. A section is a line in your javadoc containing 2 or more dashes, then the text 'WITHER', followed by 2 or more dashes, and nothing else on the line. If you use sections, <code>@return</code> and <code>@param</code> stripping / copying for that section is no longer done (move the <code>@param</code> line into the section).
-		</p>
-	</@f.overview>
-
-	<@f.snippets name="experimental/Wither" />
-
-	<@f.confKeys>
-		<dt>
-			<code>lombok.wither.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set)
-		</dt><dd>
-			Lombok will flag any usage of <code>@Wither</code> as a warning or error if configured.
-		</dd>
-	</@f.confKeys>
-
-	<@f.smallPrint>
-		<p>
-			Withers cannot be generated for static fields because that makes no sense.
-		</p><p>
-			Withers can be generated for abstract classes, but this generates an abstract method with the appropriate signature.
-		</p><p>
-			When applying <code>@Wither</code> to a type, static fields and fields whose name start with a $ are skipped.
-		</p><p>
-			For generating the method names, the first character of the field, if it is a lowercase character, is title-cased, otherwise, it is left unmodified. Then, <code>with</code> is prefixed.
-		</p><p>
-			No method is generated if any method already exists with the same name (case insensitive) and same parameter count. For example, <code>withX(int x)</code> will not be generated if there's already a method <code>withX(String... x)</code> even though it is technically possible to make the method. This caveat exists to prevent confusion. If the generation of a method is skipped for this reason, a warning is emitted instead. Varargs count as 0 to N parameters.
-		</p><p>
-			For <code>boolean</code> fields that start with <code>is</code> immediately followed by a title-case letter, nothing is prefixed to generate the wither name.
-		</p><p>
-			Various well known annotations about nullity cause null checks to be inserted and will be copied to the parameter. See <a href="/features/GetterSetter">Getter/Setter</a> documentation's small print for more information.
-		</p>
-	</@f.smallPrint>
-</@f.scaffold>
diff --git a/website/templates/setup/gradle.html b/website/templates/setup/gradle.html
index 53f45a71..148f20f8 100644
--- a/website/templates/setup/gradle.html
+++ b/website/templates/setup/gradle.html
@@ -11,7 +11,7 @@
 
 	<@s.section title="The Lombok Gradle Plugin">
 		<p>
-			There is a plugin for gradle that we recommend you use; it makes deployment a breeze, works around shortcomings of gradle prior to v2.12, and makes it easy to do additional tasks, such as running the lombok eclipse installer or delomboking. The plugin is open source. Read more <a href="https://plugins.gradle.org/plugin/io.freefair.lombok">about the gradle-lombok plugin</a>.
+			There is a plugin for gradle that we recommend you use; it makes deployment a breeze, and makes it easy to do additional tasks, such as delomboking. The plugin is open source. Read more <a href="https://plugins.gradle.org/plugin/io.freefair.lombok">about the gradle-lombok plugin</a>.
 		</p>
 	</@s.section>