Fixed up and extended Tolerate with support for constructors, and added docs.

5 files changed, 22 insertions, 65 deletions

diff --git a/website/features/Constructor.html b/website/features/Constructor.html
index a3163bfa..6dbbc0de 100644
--- a/website/features/Constructor.html
+++ b/website/features/Constructor.html
@@ -43,9 +43,7 @@
 			the <code>@ConstructorProperties</code> annotation, add a parameter to your annotation: <code>@AllArgsConstructor(suppressConstructorProperties=true)</code>. However,
 			as java 1.5, which has already been end-of-lifed, fades into obscurity, this parameter will eventually be removed. It has also been marked deprecated for this reason.
 			</p><p>
-			Unlike most other lombok annotations, the existence of an explicit constructor does not stop these annotations from generating their own constructor. This means you can write
-			your own specialized constructor, and let lombok generate the boilerplate ones as well. If a conflict arises (one of your constructors ends up with the same
-			signature as one that lombok generates), a compiler error will occur.
+			Unlike most other lombok annotations, the existence of an explicit constructor does not stop these annotations from generating their own constructor. This means you can write your own specialized constructor, and let lombok generate the boilerplate ones as well. If a conflict arises (one of your constructors ends up with the same signature as one that lombok generates), a compiler error will occur.
 			</p>
 		</div>
 		<div class="snippets">
diff --git a/website/features/Data.html b/website/features/Data.html
index 3ae03df1..c3d0a644 100644
--- a/website/features/Data.html
+++ b/website/features/Data.html
@@ -16,35 +16,18 @@
 		<div class="overview">
 			<h3>Overview</h3>
 			<p>
-			<code>@Data</code> is a convenient shortcut annotation that bundles the features of <a href="ToString.html"><code>@ToString</code></a>,
-			<a href="EqualsAndHashCode.html"><code>@EqualsAndHashCode</code></a>, <a href="GetterSetter.html"><code>@Getter</code> / <code>@Setter</code></a>
-			and <a href="Constructor.html"><code>@RequiredArgsConstructor</code></a> together: In other words, <code>@Data</code> generates <em>all</em> the
-			boilerplate that is normally associated with simple POJOs (Plain Old Java Objects) and beans: getters for all fields, setters for all non-final fields,
-			and appropriate <code>toString</code>, <code>equals</code> and <code>hashCode</code> implementations that involve the fields of the class, and a constructor that
-			initializes all final fields, as well as all non-final fields with no initializer that have been marked with <code>@NonNull</code>,
-			in order to ensure the field is never null.
+			<code>@Data</code> is a convenient shortcut annotation that bundles the features of <a href="ToString.html"><code>@ToString</code></a>, <a href="EqualsAndHashCode.html"><code>@EqualsAndHashCode</code></a>, <a href="GetterSetter.html"><code>@Getter</code> / <code>@Setter</code></a> and <a href="Constructor.html"><code>@RequiredArgsConstructor</code></a> together: In other words, <code>@Data</code> generates <em>all</em> the boilerplate that is normally associated with simple POJOs (Plain Old Java Objects) and beans: getters for all fields, setters for all non-final fields, and appropriate <code>toString</code>, <code>equals</code> and <code>hashCode</code> implementations that involve the fields of the class, and a constructor that initializes all final fields, as well as all non-final fields with no initializer that have been marked with <code>@NonNull</code>, in order to ensure the field is never null.
 			</p><p>
-			<code>@Data</code> is like having implicit <code>@Getter</code>, <code>@Setter</code>, <code>@ToString</code>, <code>@EqualsAndHashCode</code> and <code>@RequiredArgsConstructor</code>
-			annotations on the class. However, the parameters of these annotations (such as <code>callSuper</code>, <code>includeFieldNames</code> and
-			<code>exclude</code>) cannot be set with <code>@Data</code>. If you need to set non-default values for any of these parameters, just add those annotations
-			explicitly; <code>@Data</code> is smart enough to defer to those annotations.
+			<code>@Data</code> is like having implicit <code>@Getter</code>, <code>@Setter</code>, <code>@ToString</code>, <code>@EqualsAndHashCode</code> and <code>@RequiredArgsConstructor</code> annotations on the class. However, the parameters of these annotations (such as <code>callSuper</code>, <code>includeFieldNames</code> and <code>exclude</code>) cannot be set with <code>@Data</code>. If you need to set non-default values for any of these parameters, just add those annotations explicitly; <code>@Data</code> is smart enough to defer to those annotations.
 			</p><p>
-			All generated getters and setters will be <code>public</code>. To override the access level, annotate the field or class with an explicit <code>@Setter</code> and/or
-			<code>@Getter</code> annotation. You can also use this annotation (by combining it with <code>AccessLevel.NONE</code>) to suppress generating a getter and/or setter
-			altogether.
+			All generated getters and setters will be <code>public</code>. To override the access level, annotate the field or class with an explicit <code>@Setter</code> and/or <code>@Getter</code> annotation. You can also use this annotation (by combining it with <code>AccessLevel.NONE</code>) to suppress generating a getter and/or setter altogether.
 			</p><p>
-			All fields marked as <code>transient</code> will not be considered for <code>hashCode</code> and <code>equals</code>. All static fields will be
-			skipped entirely (not considered for any of the generated methods, and no setter/getter will be made for them).
+			All fields marked as <code>transient</code> will not be considered for <code>hashCode</code> and <code>equals</code>. All static fields will be skipped entirely (not considered for any of the generated methods, and no setter/getter will be made for them).
 			</p><p>
-			If the class already contains a method with the same name as any method that would normally be generated, that method is not generated, and no warning or
-			error is emitted. For example, if you already have a method with signature <code>void hashCode(int a, int b, int c)</code>, no <code>int hashCode()</code>
-			method will be generated, even though technically <code>int hashCode()</code> is an entirely different method. The same rule applies to the constructor (any explicit constructor will prevent <code>@Data</code> from generating one),
-			<code>toString</code>, <code>equals</code>, and all getters and setters.
+			If the class already contains a method with the same name and parameter count as any method that would normally be generated, that method is not generated, and no warning or error is emitted. For example, if you already have a method with signature <code>equals(AnyType param)</code>, no <code>equals</code> method will be generated, even though technically it might be an entirely different method due to having different parameter types. The same rule applies to the constructor (any explicit constructor will prevent <code>@Data</code> from generating one), as well as <code>toString</code>, <code>equals</code>, and all getters and setters. You can mark any constructor or method with <code>@lombok.experimental.Tolerate</code> to hide them from lombok.
 			</p><p>
 			<code>@Data</code> can handle generics parameters for fields just fine. In order to reduce the boilerplate when constructing objects for classes with
-			generics, you can use the <code>staticConstructor</code> parameter to generate a private constructor, as well as a static method that returns a new
-			instance. This way, javac will infer the variable name. Thus, by declaring like so: <code>@Data(staticConstructor="of") class Foo&lt;T&gt; { private T x;}</code>
-			you can create new instances of <code>Foo</code> by writing: <code>Foo.of(5);</code> instead of having to write: <code>new Foo&lt;Integer&gt;(5);</code>.
+			generics, you can use the <code>staticConstructor</code> parameter to generate a private constructor, as well as a static method that returns a new instance. This way, javac will infer the variable name. Thus, by declaring like so: <code>@Data(staticConstructor="of") class Foo&lt;T&gt; { private T x;}</code> you can create new instances of <code>Foo</code> by writing: <code>Foo.of(5);</code> instead of having to write: <code>new Foo&lt;Integer&gt;(5);</code>.
 			</p>
 		</div>
 		<div class="snippets">
diff --git a/website/features/EqualsAndHashCode.html b/website/features/EqualsAndHashCode.html
index 89d71502..32dcb6c3 100644
--- a/website/features/EqualsAndHashCode.html
+++ b/website/features/EqualsAndHashCode.html
@@ -15,22 +15,11 @@
 		<div class="overview">
 			<h3>Overview</h3>
 			<p>
-			Any class definition may be annotated with <code>@EqualsAndHashCode</code> to let lombok generate implementations of the
-			<code>equals(Object other)</code> and <code>hashCode()</code> methods. By default, it'll use all non-static, non-transient
-			fields, but you can exclude more fields by naming them in the optional <code>exclude</code> parameter to the annotation.
-			Alternatively, you can specify exactly which fields you wish to be used by naming them in the <code>of</code> parameter.
+			Any class definition may be annotated with <code>@EqualsAndHashCode</code> to let lombok generate implementations of the <code>equals(Object other)</code> and <code>hashCode()</code> methods. By default, it'll use all non-static, non-transient fields, but you can exclude more fields by naming them in the optional <code>exclude</code> parameter to the annotation. Alternatively, you can specify exactly which fields you wish to be used by naming them in the <code>of</code> parameter.
 			</p><p>
-			By setting <code>callSuper</code> to <em>true</em>, you can include the <code>equals</code> and <code>hashCode</code> methods of your superclass in the generated methods.
-			For <code>hashCode</code>, the result of <code>super.hashCode()</code> is included in the hash algorithm, and for <code>equals</code>, the generated method will return
-			false if the super implementation thinks it is not equal to the passed in object. Be aware that not all <code>equals</code> implementations handle this situation properly.
-			However, lombok-generated <code>equals</code> implementations <strong>do</strong> handle this situation properly, so you can safely call your superclass equals if it, too,
-			has a lombok-generated <code>equals</code> method.<br />
+			By setting <code>callSuper</code> to <em>true</em>, you can include the <code>equals</code> and <code>hashCode</code> methods of your superclass in the generated methods. For <code>hashCode</code>, the result of <code>super.hashCode()</code> is included in the hash algorithm, and for <code>equals</code>, the generated method will return false if the super implementation thinks it is not equal to the passed in object. Be aware that not all <code>equals</code> implementations handle this situation properly. However, lombok-generated <code>equals</code> implementations <strong>do</strong> handle this situation properly, so you can safely call your superclass equals if it, too, has a lombok-generated <code>equals</code> method.<br />
 			</p><p>
-			Setting <code>callSuper</code> to <em>true</em> when you don't extend anything (you extend <code>java.lang.Object</code>) is a compile-time error, because it would turn
-			the generated <code>equals()</code> and <code>hashCode()</code> implementations into having the same behaviour as simply inheriting these methods from <code>java.lang.Object</code>:
-			only the same object will be equal to each other and will have the same hashCode.
-			Not setting <code>callSuper</code> to <em>true</em> when you extend another class generates a warning, because unless the superclass has no (equality-important) fields, lombok
-			cannot generate an implementation for you that takes into account the fields declared by your superclasses. You'll need to write your own implementations, or rely on the
+			Setting <code>callSuper</code> to <em>true</em> when you don't extend anything (you extend <code>java.lang.Object</code>) is a compile-time error, because it would turn the generated <code>equals()</code> and <code>hashCode()</code> implementations into having the same behaviour as simply inheriting these methods from <code>java.lang.Object</code>: only the same object will be equal to each other and will have the same hashCode. Not setting <code>callSuper</code> to <em>true</em> when you extend another class generates a warning, because unless the superclass has no (equality-important) fields, lombok cannot generate an implementation for you that takes into account the fields declared by your superclasses. You'll need to write your own implementations, or rely on the
 			<code>callSuper</code> chaining facility.
 			</p><p>
 			<em>NEW in Lombok 0.10: </em>Unless your class is <code>final</code> and extends <code>java.lang.Object</code>, lombok generates a <code>canEqual</code> method
@@ -66,22 +55,15 @@
 		<div class="overview">
 			<h3>Small print</h3><div class="smallprint">
 				<p>
-				Arrays are 'deep' compared/hashCoded, which means that arrays that contain themselves will result in <code>StackOverflowError</code>s. However,
-				this behaviour is no different from e.g. <code>ArrayList</code>.
+				Arrays are 'deep' compared/hashCoded, which means that arrays that contain themselves will result in <code>StackOverflowError</code>s. However, this behaviour is no different from e.g. <code>ArrayList</code>.
 				</p><p>
-				You may safely presume that the hashCode implementation used will not change between versions of lombok, however this guarantee is not set in stone;
-				if there's a significant performance improvement to be gained from using an alternate hash algorithm, that will be substituted in a future version.
+				You may safely presume that the hashCode implementation used will not change between versions of lombok, however this guarantee is not set in stone; if there's a significant performance improvement to be gained from using an alternate hash algorithm, that will be substituted in a future version.
 				</p><p>
-				For the purposes of equality, 2 <code>NaN</code> (not a number) values for floats and doubles are considered equal, eventhough 'NaN == NaN' would
-				return false. This is analogous to <code>java.lang.Double</code>'s equals method, and is in fact required to ensure that comparing an object
-				to an exact copy of itself returns <code>true</code> for equality.
+				For the purposes of equality, 2 <code>NaN</code> (not a number) values for floats and doubles are considered equal, eventhough 'NaN == NaN' would return false. This is analogous to <code>java.lang.Double</code>'s equals method, and is in fact required to ensure that comparing an object to an exact copy of itself returns <code>true</code> for equality.
 				</p><p>
-				If there is <em>any</em> method named either <code>hashCode</code> or <code>equals</code>, regardless of return type, no methods will be generated, and a warning is emitted instead. These 2 methods need to be in sync with
-				each other, which lombok cannot guarantee unless it generates all the methods, hence you always get a warning if one <em>or</em> both
-				of the methods already exist.
+				If there is <em>any</em> method named either <code>hashCode</code> or <code>equals</code>, regardless of return type, no methods will be generated, and a warning is emitted instead. These 2 methods need to be in sync with each other, which lombok cannot guarantee unless it generates all the methods, hence you always get a warning if one <em>or</em> both of the methods already exist. You can mark any method with <code>@lombok.experimental.Tolerate</code> to hide them from lombok.
 				</p><p>
-				Attempting to exclude fields that don't exist or would have been excluded anyway (because they are static or transient) results in warnings on the named fields.
-				You therefore don't have to worry about typos.
+				Attempting to exclude fields that don't exist or would have been excluded anyway (because they are static or transient) results in warnings on the named fields. You therefore don't have to worry about typos.
 				</p><p>
 				Having both <code>exclude</code> and <code>of</code> generates a warning; the <code>exclude</code> parameter will be ignored in that case.
 				</p><p>
diff --git a/website/features/ToString.html b/website/features/ToString.html
index 6cdd8453..57bbd0f0 100644
--- a/website/features/ToString.html
+++ b/website/features/ToString.html
@@ -15,18 +15,13 @@
 		<div class="overview">
 			<h3>Overview</h3>
 			<p>
-			Any class definition may be annotated with <code>@ToString</code> to let lombok generate an implementation of the
-			<code>toString()</code> method. By default, it'll print your class name, along with each field, in order, separated by commas.
+			Any class definition may be annotated with <code>@ToString</code> to let lombok generate an implementation of the <code>toString()</code> method. By default, it'll print your class name, along with each field, in order, separated by commas.
 			</p><p>
-			By setting the <code>includeFieldNames</code> parameter to <em>true</em> you can add some clarity (but also quite some length) to
-			the output of the <code>toString()</code> method.
+			By setting the <code>includeFieldNames</code> parameter to <em>true</em> you can add some clarity (but also quite some length) to the output of the <code>toString()</code> method.
 			</p><p>
-			By default, all non-static fields will be printed. If you want to skip some fields, you can name them in the <code>exclude</code> parameter; each named
-			field will not be printed at all. Alternatively, you can specify exactly which fields you wish to be used by naming them in the <code>of</code> parameter.
+			By default, all non-static fields will be printed. If you want to skip some fields, you can name them in the <code>exclude</code> parameter; each named field will not be printed at all. Alternatively, you can specify exactly which fields you wish to be used by naming them in the <code>of</code> parameter.
 			</p><p>
-			By setting <code>callSuper</code> to <em>true</em>, you can include the output of the superclass implementation of <code>toString</code> to the
-			output. Be aware that the default implementation of <code>toString()</code> in <code>java.lang.Object</code> is pretty much meaningless, so you
-			probably don't want to do this unless you are extending another class.
+			By setting <code>callSuper</code> to <em>true</em>, you can include the output of the superclass implementation of <code>toString</code> to the output. Be aware that the default implementation of <code>toString()</code> in <code>java.lang.Object</code> is pretty much meaningless, so you probably don't want to do this unless you are extending another class.
 			</p>
 		</div>
 		<div class="snippets">
@@ -55,8 +50,7 @@
 		<div class="overview">
 			<h3>Small print</h3><div class="smallprint">
 				<p>
-				If there is <em>any</em> method named <code>toString</code> regardless of parameters or return type, no method will be generated, and instead
-				a warning is emitted explaining that your <code>@ToString</code> annotation is doing nothing.
+				If there is <em>any</em> method named <code>toString</code> with no arguments, regardless of return type, no method will be generated, and instead a warning is emitted explaining that your <code>@ToString</code> annotation is doing nothing. You can mark any method with <code>@lombok.experimental.Tolerate</code> to hide them from lombok.
 				</p><p>
 				Arrays are printed via <code>Arrays.deepToString</code>, which means that arrays that contain themselves will result in <code>StackOverflowError</code>s. However,
 				this behaviour is no different from e.g. <code>ArrayList</code>.
diff --git a/website/features/Value.html b/website/features/Value.html
index 09557c6a..50309689 100644
--- a/website/features/Value.html
+++ b/website/features/Value.html
@@ -27,11 +27,11 @@
 				<code>@Value</code> is the immutable variant of <a href="Data.html"><code>@Data</code></a>; all fields are made <code>private</code> and <code>final</code> by default, and setters are not generated. The class itself is also made <code>final</code> by default, because immutability is not something that can be forced onto a subclass. Like <code>@Data</code>, useful <code>toString()</code>, <code>equals()</code> and <code>hashCode()</code> methods are also generated, each field gets a getter method, and a constructor that covers every
 				argument (except <code>final</code> fields that are initialized in the field declaration) is also generated.
 			</p><p>
-				In practice, <code>@Value</code> is shorthand for: <code>final @ToString @EqualsAndHashCode @AllArgsConstructor @FieldDefaults(makeFinal = true, level = AccessLevel.PRIVATE) @Getter</code>, except that explicitly including an implementation of any of the relevant methods simply means that part won't be generated and no warning will be emitted. For example, if you write your own <code>toString</code>, no error occurs, and lombok will not generate a <code>toString</code>. Also, <em>any</em> explicit constructor, no matter the arguments list, implies lombok will not generate a constructor. If you do want lombok to generate the all-args constructor, add <code>@AllArgsConstructor</code> to the class.
+				In practice, <code>@Value</code> is shorthand for: <code>final @ToString @EqualsAndHashCode @AllArgsConstructor @FieldDefaults(makeFinal = true, level = AccessLevel.PRIVATE) @Getter</code>, except that explicitly including an implementation of any of the relevant methods simply means that part won't be generated and no warning will be emitted. For example, if you write your own <code>toString</code>, no error occurs, and lombok will not generate a <code>toString</code>. Also, <em>any</em> explicit constructor, no matter the arguments list, implies lombok will not generate a constructor. If you do want lombok to generate the all-args constructor, add <code>@AllArgsConstructor</code> to the class. You can mark any constructor or method with <code>@lombok.experimental.Tolerate</code> to hide them from lombok.
 			</p><p>
 				It is possible to override the final-by-default and private-by-default behaviour using either an explicit access level on a field, or by using the <code>@NonFinal</code> or <code>@PackagePrivate</code> annotations.<br />
 				It is possible to override any default behaviour for any of the 'parts' that make up <code>@Value</code> by explicitly using that annotation.
-				</p>
+			</p>
 		</div>
 		<div class="snippets">
 			<div class="pre">