From 72fd50b9f1db1ab6bfc1753ba6a1e686a2f0f22c Mon Sep 17 00:00:00 2001
From: Reinier Zwitserloot <reinier@zwitserloot.com>
Date: Mon, 8 May 2017 21:11:15 +0200
Subject: moved an update to the website text about the jdk8 onX support to the
 new website templates.

---
 website2/templates/features/Builder.html          | 15 +++++++++++++--
 website2/templates/features/constructor.html      |  2 +-
 website2/templates/features/experimental/onX.html |  6 +++++-
 3 files changed, 19 insertions(+), 4 deletions(-)

(limited to 'website2')

diff --git a/website2/templates/features/Builder.html b/website2/templates/features/Builder.html
index 238fada3..a6b8d18f 100644
--- a/website2/templates/features/Builder.html
+++ b/website2/templates/features/Builder.html
@@ -8,6 +8,8 @@
 			<code>@Builder</code> gained <code>@Singular</code> support and was promoted to the main <code>lombok</code> package since lombok v1.16.0.
 		</p><p>
 			<code>@Builder</code> with <code>@Singular</code> adds a clear method since lombok v1.16.8.
+		</p><p>
+			<code>@Builder.Default</code> functionality was added in lombok v1.16.16.
 		</p>
 	</@f.history>
 	
@@ -66,10 +68,19 @@
 			<code>@Builder(builderClassName = "HelloWorldBuilder", buildMethodName = "execute", builderMethodName = "helloWorld", toBuilder = true)</code><br />
 		</p>
 	</@f.overview>
-
+	
+	<@f.featureSection>
+		<h3 id="builderdefault"><a name="builderdefault">@Builder.Default</a></h3>
+		
+		<p>
+			If a certain field/parameter is never set during a build session, then it always gets 0 / <code>null</code> / false. If you've put <code>@Builder</code> on a class (and not a method or constructor) you can instead specify the default directly on the field, and annotate the field with <code>@Builder.Default</code>:<br />
+			<code>@Builder.Default private final long created = System.currentTimeMillis();</code>	</@f.featureSection>
+		</p>
+	</@f.featureSection>
+	
 	<@f.featureSection>
 		<h3 id="singular"><a name="singular">@Singular</a></h3>
-
+		
 		<p>
 			By annotating one of the parameters (if annotating a method or constructor with <code>@Builder</code>) or fields (if annotating a class with <code>@Builder</code>) with the <code>@Singular</code> annotation, lombok will treat that builder node as a collection, and it generates 2 'adder' methods instead of a 'setter' method. One which adds a single element to the collection, and one which adds all elements of another collection to the collection. No setter to just set the collection (replacing whatever was already added) will be generated. A 'clear' method is also generated. These 'singular' builders are very complicated in order to guarantee the following properties:
 			<ul>
diff --git a/website2/templates/features/constructor.html b/website2/templates/features/constructor.html
index fb331113..6a12fa2a 100644
--- a/website2/templates/features/constructor.html
+++ b/website2/templates/features/constructor.html
@@ -45,7 +45,7 @@
 		<p>
 			Even if a field is explicitly initialized with <code>null</code>, lombok will consider the requirement to avoid null as fulfilled, and will <em>NOT</em> consider the field as a 'required' argument. The assumption is that if you explicitly assign <code>null</code> to a field that you've also marked as <code>@NonNull</code> signals you must know what you're doing.
 		</p><p>
-			The <code>@java.beans.ConstructorProperties</code> annotation is never generated for a constructor with no arguments. This also explains why <code>@NoArgsConstructor</code> lacks the <code>suppressConstructorProperties</code> annotation method. The <code>@ConstructorProperties</code> annotation is also omitted for private constructors. The generated static factory methods also do not get <code>@ConstructorProperties</code>, as this annotation can only be added to real constructors.
+			The <code>@java.beans.ConstructorProperties</code> annotation is never generated for a constructor with no arguments. This also explains why <code>@NoArgsConstructor</code> lacks the <code>suppressConstructorProperties</code> annotation method. The generated static factory methods also do not get <code>@ConstructorProperties</code>, as this annotation can only be added to real constructors.
 		</p><p>
 			<code>@XArgsConstructor</code> can also be used on an enum definition. The generated constructor will always be private, because non-private constructors aren't legal in enums. You don't have to specify <code>AccessLevel.PRIVATE</code>.
 		</p><p>
diff --git a/website2/templates/features/experimental/onX.html b/website2/templates/features/experimental/onX.html
index 8e07f0ac..fd2e7b58 100644
--- a/website2/templates/features/experimental/onX.html
+++ b/website2/templates/features/experimental/onX.html
@@ -32,7 +32,9 @@
 		</p><p>
 			<code>@Setter</code> and <code>@Wither</code> support <code>onParam</code> in addition to <code>onMethod</code>; annotations listed will be put on the only parameter that the generated method has. <code>@EqualsAndHashCode</code> also supports <code>onParam</code>; the listed annotation(s) will be placed on the single parameter of the generated <code>equals</code> method, as well as any generated <code>canEqual</code> method.
 		</p><p>
-			The syntax is a little strange; to use any of the 3 <code>onX</code> features, you must wrap the annotations to be applied to the constructor / method / parameter in <code>@__(@AnnotationGoesHere)</code>. To apply multiple annotations, use <code>@__({@Annotation1, @Annotation2})</code>. The annotations can themselves obviously have parameters as well.
+			The syntax is a little strange and depends on the javac you are using.<br />
+			On javac7, to use any of the 3 <code>onX</code> features, you must wrap the annotations to be applied to the constructor / method / parameter in <code>@__(@AnnotationGoesHere)</code>. To apply multiple annotations, use <code>@__({@Annotation1, @Annotation2})</code>. The annotations can themselves obviously have parameters as well.<br />
+			On javac8 and up, you add an underscore after <code>onMethod</code>, <code>onParam</code>, or <code>onConstructor</code>.
 		</p>
 	</@f.overview>
 
@@ -49,6 +51,8 @@
 	<@f.smallPrint>
 		<p>
 			The reason of the weird syntax is to make this feature work in javac 7 compilers; the <code>@__</code> type is an annotation reference to the annotation type <code>__</code> (double underscore) which doesn't actually exist; this makes javac 7 delay aborting the compilation process due to an error because it is possible an annotation processor will later create the <code>__</code> type. Instead, lombok applies the annotations and removes the references so that the error will never actually occur. The point is: The <code>__</code> type <em>must not exist</em>, otherwise the feature does not work. In the rare case that the <code>__</code> type does exist (and is imported or in the package), you can simply add more underscores. Technically any non-existent type would work, but to maintain consistency and readability and catch erroneous use, lombok considers it an error if the 'wrapper' annotation is anything but a series of underscores.
+		</p><p>
+			In javac8, the above feature should work but due to a bug in javac8 it does not. However, starting in javac8, if the parameter name does not exist in the annotation type, compilation proceeds to a phase where lombok can fix it.
 		</p><p>
 			To reiterate: This feature can disappear at any time; if you use this feature, be prepared to adjust your code when we find a nicer way of implementing this feature, or, if a future version of javac forces us to remove this feature entirely with no alternative.
 		</p><p>
-- 
cgit