From 693af13472fc4c474edcb163e09cfe87b4c71f3e Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Thu, 12 Sep 2019 21:22:25 +0200 Subject: [website] Updating feature and experimental overviews to properly include the With promotion. --- website/templates/features/With.html | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'website/templates/features/With.html') diff --git a/website/templates/features/With.html b/website/templates/features/With.html index 35c52dab..f1719e19 100644 --- a/website/templates/features/With.html +++ b/website/templates/features/With.html @@ -13,14 +13,15 @@ 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 @With generates: a withFieldName(newValue) method which produces a clone except for the new value for the associated field.

For example, if you create public class Point { private final int x, y; }, setters make no sense because the fields are final. @With can generate a withX(int newXValue) method for you which will return a new point with the supplied value for x and the same value for y. +

+ The @With relies on a constructor for all fields in order to do its work. If this constructor does not exist, your @With annotation will result in a compile time error message. Lombok's own @AllArgsConstructor. As Value will automatically produce an all args constructor as well, you can use that too. It's of course also acceptable if you manually write this constructor. It must contain all non-static fields, in the same lexical order.

Like @Setter, you can specify an access level in case you want the generated with method to be something other than public:
@With(level = AccessLevel.PROTECTED). Also like @Setter, you can also put a @With annotation on a type, which means a with method is generated for each field (even non-final fields).

To put annotations on the generated method, you can use onMethod=@__({@AnnotationsHere}). Be careful though! This is an experimental feature. For more details see the documentation on the onX feature.

javadoc on the field will be copied to generated with methods. Normally, all text is copied, and @param is moved to the with method, whilst @return 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 WITH. 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, @return and @param stripping / copying for that section is no longer done (move the @param line into the section). -

- If you have a hierarchical immutable data structure, the @WithBy feature might be more suitable than @With +

<@f.snippets name="With" /> @@ -44,8 +45,6 @@ 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, with is prefixed.

No method is generated if any method already exists with the same name (case insensitive) and same parameter count. For example, withX(int x) will not be generated if there's already a method withX(String... x) 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. -

- For boolean fields that start with is immediately followed by a title-case letter, nothing is prefixed to generate the wither name.

Various well known annotations about nullity cause null checks to be inserted and will be copied to the parameter. See Getter/Setter documentation's small print for more information.

-- cgit