diff options
Diffstat (limited to 'website/features')
| -rw-r--r-- | website/features/Builder.html | 25 | ||||
| -rw-r--r-- | website/features/NonNull.html | 5 | ||||
| -rw-r--r-- | website/features/configuration.html | 9 | ||||
| -rw-r--r-- | website/features/experimental/FieldDefaults.html | 4 |
4 files changed, 30 insertions, 13 deletions
diff --git a/website/features/Builder.html b/website/features/Builder.html index c6f51ff1..88083a27 100644 --- a/website/features/Builder.html +++ b/website/features/Builder.html @@ -18,7 +18,8 @@ <code>@Builder</code> was introduced as experimental feature in lombok v0.12.0. </p><p> <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><p> + <code>@Builder</code> with <code>@Singular</code> adds a clear method since lombok v1.16.8. </div> <div class="overview"> <h3>Overview</h3> @@ -28,16 +29,16 @@ <code>@Builder</code> lets you automatically produce the code required to have your class be instantiable with code such as:<br /> <code>Person.builder().name("Adam Savage").city("San Francisco").job("Mythbusters").job("Unchained Reaction").build();</code> </p><p> - <code>@Builder</code> can be placed on a class, or on a constructor, or on a static method. While the "on a class" and "on a constructor" - mode are the most common use-case, <code>@Builder</code> is most easily explained with the "static method" use-case. + <code>@Builder</code> can be placed on a class, or on a constructor, or on a method. While the "on a class" and "on a constructor" + mode are the most common use-case, <code>@Builder</code> is most easily explained with the "method" use-case. </p><p> - A static method annotated with <code>@Builder</code> (from now on called the <em>target</em>) causes the following 7 things to be generated:<ul> - <li>An inner static class named <code><em>Foo</em>Builder</code>, with the same type arguments as the static method (called the <em>builder</em>).</li> + A method annotated with <code>@Builder</code> (from now on called the <em>target</em>) causes the following 7 things to be generated:<ul> + <li>An inner class named <code><em>Foo</em>Builder</code>, with the same type arguments as the method (called the <em>builder</em>).</li> <li>In the <em>builder</em>: One private non-static non-final field for each parameter of the <em>target</em>.</li> <li>In the <em>builder</em>: A package private no-args empty constructor.</li> <li>In the <em>builder</em>: A 'setter'-like method for each parameter of the <em>target</em>: It has the same type as that parameter and the same name. It returns the builder itself, so that the setter calls can be chained, as in the above example.</li> - <li>In the <em>builder</em>: A <code>build()</code> method which calls the static method, passing in each field. It returns the same type that the + <li>In the <em>builder</em>: A <code>build()</code> method which calls the method, passing in each field. It returns the same type that the <em>target</em> returns.</li> <li>In the <em>builder</em>: A sensible <code>toString()</code> implementation.</li> <li>In the class containing the <em>target</em>: A static <code>builder()</code> method, which creates a new instance of the <em>builder</em>.</li> @@ -51,7 +52,7 @@ element to the list. For example: <code>Person.builder().job("Mythbusters").job("Unchained Reaction").build();</code> would result in the <code>List<String> jobs</code> field to have 2 strings in it. To get this behaviour, the field/parameter needs to be annotated with <code>@Singular</code>. The feature has <a href="#singular">its own documentation</a>. </p><p> - Now that the "static method" mode is clear, putting a <code>@Builder</code> annotation on a constructor functions similarly; effectively, + Now that the "method" mode is clear, putting a <code>@Builder</code> annotation on a constructor functions similarly; effectively, constructors are just static methods that have a special syntax to invoke them: Their 'return type' is the class they construct, and their type parameters are the same as the type parameters of the class itself. </p><p> @@ -63,8 +64,8 @@ </p><p> The name of the builder class is <code><em>Foobar</em>Builder</code>, where <em>Foobar</em> is the simplified, title-cased form of the return type of the <em>target</em> - that is, the name of your type for <code>@Builder</code> on constructors and types, and the name of the return type for <code>@Builder</code> - on static methods. For example, if <code>@Builder</code> is applied to a class named <code>com.yoyodyne.FancyList<T></code>, then the builder name will be - <code>FancyListBuilder<T></code>. If <code>@Builder</code> is applied to a static method that returns <code>void</code>, the builder will be named + on methods. For example, if <code>@Builder</code> is applied to a class named <code>com.yoyodyne.FancyList<T></code>, then the builder name will be + <code>FancyListBuilder<T></code>. If <code>@Builder</code> is applied to a method that returns <code>void</code>, the builder will be named <code>VoidBuilder</code>. </p><p> The configurable aspects of builder are:<ul> @@ -80,13 +81,13 @@ <div class="overview"> <h3><a name="singular">@Singular</a></h3> <p> - By annotating one of the parameters (if annotating a static method or constructor with <code>@Builder</code>) or fields (if annotating a class with <code>@Builder</code>) with the + 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. These 'singular' builders + 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> <li>When invoking <code>build()</code>, the produced collection will be immutable.</li> - <li>Calling one of the 'adder' methods after invoking <code>build()</code> does not modify any already generated objects, and, if <code>build()</code> is later called again, another collection with all the elements added since the creation of the builder is generated.</li> + <li>Calling one of the 'adder' methods, or the 'clear' method, after invoking <code>build()</code> does not modify any already generated objects, and, if <code>build()</code> is later called again, another collection with all the elements added since the creation of the builder is generated.</li> <li>The produced collection will be compacted to the smallest feasible format while remaining efficient.</li> </ul> </p><p> diff --git a/website/features/NonNull.html b/website/features/NonNull.html index d62441f4..50acf627 100644 --- a/website/features/NonNull.html +++ b/website/features/NonNull.html @@ -15,7 +15,7 @@ <div class="overview"> <h3>Overview</h3> <p> - <em>NEW in Lombok 0.11.10: </em>You can use <code>@NonNull</code> on the parameter of a method or constructor to have lombok generate a null-check statement for you. + <em>NEW in Lombok 0.11.10: </em>You can use <code>@NonNull</code> on the parameter of a method or constructor to have lombok generate a null-check statement for you.<br /> </p><p> Lombok has always treated any annotation named <code>@NonNull</code> on a field as a signal to generate a null-check if lombok generates an entire method or constructor for you, via for example <a href="Data.html"><code>@Data</code></a>. Now, however, using lombok's own <code>@lombok.NonNull</code> on a parameter results in the insertion of just the null-check @@ -60,6 +60,9 @@ this feature only triggers on lombok's own <code>@NonNull</code> annotation from the <code>lombok</code> package. </p><p> A <code>@NonNull</code> on a primitive parameter results in a warning. No null-check will be generated. + </p><p> + A <code>@NonNull</code> on a parameter of an abstract method used to generate a warning; starting with version 1.16.8, this is no longer the case, to acknowledge the notion that <code>@NonNull</code> also has a + documentary role. For the same reason, you can annotate a method as <code>@NonNull</code>; this is allowed, generates no warning, and does not generate any code. </p> </div> </div> diff --git a/website/features/configuration.html b/website/features/configuration.html index 7e79a9c0..21864409 100644 --- a/website/features/configuration.html +++ b/website/features/configuration.html @@ -85,6 +85,15 @@ <code>lombok.extern.findbugs.addSuppressFBWarnings = true</code> </div> </div> + <div class="overview" style="clear: left;"> + <h3>Config keys that can even affect source files with 0 lombok annotations</h3> + <p> + <div class="snippet example"> + <code>lombok.fieldDefaults.defaultPrivate = true</code><br /> + <code>lombok.fieldDefaults.defaultFinal = true</code> + </div> + Turning either of these options on means lombok will make <em>every</em> field in <em>every</em> source file final and/or private unless it has an explicit access modifier or annotation to suppress this. <a href="experimental/FieldDefaults.html">See the <code>@FieldDefaults</code> documentation for more</a>. + </div> <div style="clear: left;"></div> <div class="footer"> <a href="index.html">Back to features</a> | <a href="Log.html">Previous feature (@Log)</a> | <span class="disabled">Next feature</span><br /> diff --git a/website/features/experimental/FieldDefaults.html b/website/features/experimental/FieldDefaults.html index 5ad30952..026f23fc 100644 --- a/website/features/experimental/FieldDefaults.html +++ b/website/features/experimental/FieldDefaults.html @@ -61,6 +61,10 @@ <dl> <dt><code>lombok.fieldDefaults.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set)</dt> <dd>Lombok will flag any usage of <code>@FieldDefaults</code> as a warning or error if configured.</dd> + <dt><code>lombok.fieldDefaults.defaultPrivate</code> = [<code>true</code> | <code>false</code>] (default: false)</dt> + <dd>(Since 1.16.8) If set to <code>true</code>, <em>every</em> field in <em>every</em> class or enum anywhere in the sources being compiled will be marked as <code>private</code> unless it has an explicit access modifier or the <code>@PackagePrivate</code> annotation, or an explicit <code>@FieldDefaults</code> annotation is present to override this config key.</dd> + <dt><code>lombok.fieldDefaults.defaultFinal</code> = [<code>true</code> | <code>false</code>] (default: false)</dt> + <dd>(Since 1.16.8) If set to <code>true</code>, <em>every</em> field in <em>every</em> class or enum anywhere in the sources being compiled will be marked as <code>final</code> unless it has the <code>@NonFinal</code> annotation, or an explicit <code>@FieldDefaults</code> annotation is present to override this config key.</dd> </dl> </div> <div class="overview"> |