From aee4e76d864e01b5d453409e703ad54852fa57bb Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Tue, 18 Sep 2018 01:40:32 +0200 Subject: updated docs to reflect change to copyable annotations --- website/templates/features/Builder.html | 2 ++ website/templates/features/Data.html | 2 +- website/templates/features/GetterSetter.html | 4 +++- website/templates/features/Value.html | 2 ++ website/templates/features/constructor.html | 2 ++ website/templates/features/experimental/SuperBuilder.html | 2 ++ website/templates/features/experimental/Wither.html | 2 +- 7 files changed, 13 insertions(+), 3 deletions(-) (limited to 'website') diff --git a/website/templates/features/Builder.html b/website/templates/features/Builder.html index bc03749e..793c7b54 100644 --- a/website/templates/features/Builder.html +++ b/website/templates/features/Builder.html @@ -181,6 +181,8 @@ public class JacksonExample { With toBuilder = true applied to methods, any type parameter of the annotated method itself must also show up in the return type.

The initializer on a @Builder.Default field is removed and stored in a static method, in order to guarantee that this initializer won't be executed at all if a value is specified in the build. This does mean the initializer cannot refer to this, super or any non-static member. If lombok generates a constructor for you, it'll also initialize this field with the initializer. +

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

diff --git a/website/templates/features/Data.html b/website/templates/features/Data.html index 59370cc8..36278819 100644 --- a/website/templates/features/Data.html +++ b/website/templates/features/Data.html @@ -33,7 +33,7 @@

See the small print of @ToString, @EqualsAndHashCode, @Getter / @Setter and @RequiredArgsConstructor.

- Any annotations named @NonNull (case insensitive) on a field are interpreted as: This field must not ever hold null. Therefore, these annotations result in an explicit null check in the generated constructor for the provided field. Also, these annotations (as well as any annotation named @Nullable) are copied to the constructor parameter, in both the true constructor and any static constructor. The same principle applies to generated getters and setters (see the documentation for @Getter / @Setter) + Various well known annotations about nullity cause null checks to be inserted and will be copied to the relevant places (such as the method for getters, and the parameter for the constructor and setters). See Getter/Setter documentation's small print for more information.

By default, any variables that start with a $ symbol are excluded automatically. You can include them by specifying an explicit annotation (@Getter or @ToString, for example) and using the 'of' parameter.

diff --git a/website/templates/features/GetterSetter.html b/website/templates/features/GetterSetter.html index 1baa5bd0..04cd1ec7 100644 --- a/website/templates/features/GetterSetter.html +++ b/website/templates/features/GetterSetter.html @@ -58,7 +58,9 @@

Any variation on boolean will not result in using the is prefix instead of the get prefix; for example, returning java.lang.Boolean results in a get prefix, not an is prefix.

- Any annotations named @NonNull (case insensitive) on the field are interpreted as: This field must not ever hold null. Therefore, these annotations result in an explicit null check in the generated setter. Also, these annotations (as well as any annotation named @Nullable or @CheckForNull) are copied to setter parameter and getter method. + A number of annotations from popular libraries that indicate non-nullness, such as javax.annotation.Nonnull, if present on the field, result in an explicit null check in the generated setter. +

+ Various well-known annotations about nullability, such as org.eclipse.jdt.annotation.NonNull, are automatically copied over to the right place (method for getters, parameter for setters). You can specify additional annotations that should always be copied via lombok configuration key lombok.copyableAnnotations.

You can annotate a class with a @Getter or @Setter annotation. Doing so is equivalent to annotating all non-static fields in that class with that annotation. @Getter/@Setter annotations on fields take precedence over the ones on classes.

diff --git a/website/templates/features/Value.html b/website/templates/features/Value.html index fdad0e12..5fe188b3 100644 --- a/website/templates/features/Value.html +++ b/website/templates/features/Value.html @@ -41,6 +41,8 @@ Look for the documentation on the 'parts' of @Value: @ToString, @EqualsAndHashCode, @AllArgsConstructor, @FieldDefaults, and @Getter.

For classes with generics, it's useful to have a static method which serves as a constructor, because inference of generic parameters via static methods works in java6 and avoids having to use the diamond operator. While you can force this by applying an explicit @AllArgsConstructor(staticConstructor="of") annotation, there's also the @Value(staticConstructor="of") feature, which will make the generated all-arguments constructor private, and generates a public static method named of which is a wrapper around this private constructor. +

+ Various well known annotations about nullity cause null checks to be inserted and will be copied to the relevant places (such as the method for getters, and the parameter for the constructor and setters). See Getter/Setter documentation's small print for more information.

@Value was an experimental feature from v0.11.4 to v0.11.9 (as @lombok.experimental.Value). It has since been moved into the core package. The old annotation is still around (and is an alias). It will eventually be removed in a future version, though.

diff --git a/website/templates/features/constructor.html b/website/templates/features/constructor.html index 716efe5a..fc0be1c6 100644 --- a/website/templates/features/constructor.html +++ b/website/templates/features/constructor.html @@ -50,6 +50,8 @@ @XArgsConstructor 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 AccessLevel.PRIVATE.

While suppressConstructorProperties has been marked deprecated in anticipation of a world where all java environments have the @ConstructorProperties annotation available, first GWT 2.2 and Android 2.3.3, which do not (yet) have this annotation, will have to be ancient history before this annotation parameter will be removed. +

+ 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.

The flagUsage configuration keys do not trigger when a constructor is generated by @Data, @Value or any other lombok annotation.

diff --git a/website/templates/features/experimental/SuperBuilder.html b/website/templates/features/experimental/SuperBuilder.html index 9b49bc83..8189a254 100644 --- a/website/templates/features/experimental/SuperBuilder.html +++ b/website/templates/features/experimental/SuperBuilder.html @@ -63,6 +63,8 @@ An ArrayList is used to store added elements as call methods of a @Singular marked field, if the target collection is from the java.util package, even if the collection is a set or map. Because lombok ensures that generated collections are compacted, a new backing instance of a set or map must be constructed anyway, and storing the data as an ArrayList during the build process is more efficient that storing it as a map or set. This behaviour is not externally visible, an implementation detail of the current implementation of the java.util recipes for @Singular.

The generated builder code heavily relies on generics to avoid class casting when using the builder. +

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

diff --git a/website/templates/features/experimental/Wither.html b/website/templates/features/experimental/Wither.html index 9642458b..00dc10b1 100644 --- a/website/templates/features/experimental/Wither.html +++ b/website/templates/features/experimental/Wither.html @@ -60,7 +60,7 @@

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

- Any annotations named @NonNull (case insensitive) on the field are interpreted as: This field must not ever hold null. Therefore, these annotations result in an explicit null check in the generated wither. Also, these annotations (as well as any annotation named @Nullable or @CheckForNull) are copied to wither parameter. + 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