[documentation] documenting the new-style include/exclude of ToString and EqualsAndHashCode

1 files changed, 10 insertions, 4 deletions

diff --git a/website/templates/features/ToString.html b/website/templates/features/ToString.html
index 6f230561..d31cf35d 100644
--- a/website/templates/features/ToString.html
+++ b/website/templates/features/ToString.html
@@ -7,9 +7,13 @@
 		</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.
 		</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 annotate these fields with <code>@ToString.Exclude</code>. Alternatively, you can specify exactly which fields you wish to be used by using <code>@ToString(onlyExplicitlyIncluded = true)</code>, then marking each field you want to include with <code>@ToString.Include</code>.
 		</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.
+		</p><p>
+			You can also include the output of a method call in your <code>toString</code>. Only instance (non-static) methods that take no arguments can be included. To do so, mark the method with <code>@ToString.Include</code>.
+		</p><p>
+			You can change the name used to identify the member with <code>@ToString.Include(name = "some other name")</code>, and you can change the order in which the members are printed via <code>@ToString.Include(rank = -1)</code>. Members without a rank are considered to have rank 0, members of a higher rank are printed first, and members of the same rank are printed in the same order they appear in the source file.
 		</p>
 	</@f.overview>
 
@@ -37,13 +41,15 @@
 		</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>.
 		</p><p>
-			Attempting to exclude fields that don't exist or would have been excluded anyway (because they are static) results in warnings on the named fields. You therefore don't have to worry about typos.
+			If a method is marked for inclusion and it has the same name as a field, it replaces the toString output for that field (the method is included, the field is excluded, and the method's output is printed in the place the field would be printed).
+		</p><p>
+			Prior to lombok 1.16.22, inclusion/exclusion could be done with the <code>of</code> and <code>exclude</code> parameters of the <code>@ToString</code> annotation. This old-style inclusion mechanism is still supported but will be deprecated in the future.
 		</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.
+			Having both <code>@ToString.Exclude</code> and <code>@ToString.Include</code> on a member generates a warning; the member will be excluded in this case.
 		</p><p>
 			We don't promise to keep the output of the generated <code>toString()</code> methods the same between lombok versions. You should never design your API so that other code is forced to parse your <code>toString()</code> output anyway!
 		</p><p>
-			By default, any variables that start with a $ symbol are excluded automatically. You can only include them by using the 'of' parameter.
+			By default, any variables that start with a $ symbol are excluded automatically. You can only include them by using the <code>@ToString.Include</code> annotation.
 		</p><p>
 			If a getter exists for a field to be included, it is called instead of using a direct field reference. This behaviour can be suppressed:<br />
 			<code>@ToString(doNotUseGetters = true)</code>