diff options
Diffstat (limited to 'website')
7 files changed, 23 insertions, 11 deletions
diff --git a/website/templates/features/GetterLazy.html b/website/templates/features/GetterLazy.html index b1f374a8..e921712c 100644 --- a/website/templates/features/GetterLazy.html +++ b/website/templates/features/GetterLazy.html @@ -9,6 +9,9 @@ <p> You can let lombok generate a getter which will calculate a value once, the first time this getter is called, and cache it from then on. This can be useful if calculating the value takes a lot of CPU, or the value takes a lot of memory. To use this feature, create a <code>private final</code> variable, initialize it with the expression that's expensive to run, and annotate your field with <code>@Getter(lazy=true)</code>. The field will be hidden from the rest of your code, and the expression will be evaluated no more than once, when the getter is first called. There are no magic marker values (i.e. even if the result of your expensive calculation is <code>null</code>, the result is cached) and your expensive calculation need not be thread-safe, as lombok takes care of locking. </p> + <p> + If the initialization expression is complex, or contains generics, we recommend moving the code to a private (if possible static) method, and call that instead. + </p> </@f.overview> <@f.snippets name="GetterLazy" /> diff --git a/website/templates/features/constructor.html b/website/templates/features/constructor.html index fc0be1c6..b1f25321 100644 --- a/website/templates/features/constructor.html +++ b/website/templates/features/constructor.html @@ -17,7 +17,7 @@ </p><p> To put annotations on the generated constructor, you can use <code>onConstructor=@__({@AnnotationsHere})</code>, but be careful; this is an experimental feature. For more details see the documentation on the <a href="/features/experimental/onX">onX</a> feature. </p><p> - Static fields are skipped by these annotations. Also, a <code>@java.beans.ConstructorProperties</code> annotation is added for all constructors with at least 1 argument, which allows bean editor tools to call the generated constructors. <code>@ConstructorProperties</code> is new in Java 1.6, which means that if your code is intended for compilation on Java 1.5, a compiler error will occur. <em>Running</em> on a JVM 1.5 should be no problem (the annotation will be ignored). To suppress the generation of 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. + Static fields are skipped by these annotations. </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. </p> @@ -27,9 +27,9 @@ <@f.confKeys> <dt> - <code>lombok.anyConstructor.suppressConstructorProperties</code> = [<code>true</code> | <code>false</code>] (default: <code>false</code>) + <code>lombok.anyConstructor.addConstructorProperties</code> = [<code>true</code> | <code>false</code>] (default: <code>false</code>) </dt><dd> - If set to <code>true</code>, then lombok will skip adding a <code>@java.beans.ConstructorProperties</code> to generated constructors. This is useful in android and GWT development where that annotation is not usually available. + If set to <code>true</code>, then lombok will add a <code>@java.beans.ConstructorProperties</code> to generated constructors. </dd><dt> <code>lombok.</code>[<code>allArgsConstructor</code>|<code>requiredArgsConstructor</code>|<code>noArgsConstructor</code>]<code>.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) </dt><dd> @@ -49,8 +49,6 @@ </p><p> <code>@XArgsConstructor</code> 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 <code>AccessLevel.PRIVATE</code>. </p><p> - While <code>suppressConstructorProperties</code> has been marked deprecated in anticipation of a world where all java environments have the <code>@ConstructorProperties</code> 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. - </p><p> Various well known annotations about nullity cause null checks to be inserted and will be copied to the parameter. See <a href="/features/GetterSetter">Getter/Setter</a> documentation's small print for more information. </p><p> The <code>flagUsage</code> configuration keys do not trigger when a constructor is generated by <code>@Data</code>, <code>@Value</code> or any other lombok annotation. diff --git a/website/templates/features/delombok.html b/website/templates/features/delombok.html index 56b02f7d..75178740 100644 --- a/website/templates/features/delombok.html +++ b/website/templates/features/delombok.html @@ -23,6 +23,8 @@ </p><p> To let delombok print the transformation result of a single java file directly to standard output, you can use: <pre>java -jar lombok.jar delombok -p MyJavaFile.java</pre> + </p><p> + The <code>-classpath</code>, <code>-sourcepath</code>, and <code>--module-path</code> options of javac are replicated as <code>--classpath</code>, <code>--sourcepath</code>, and <code>--module-path</code> in delombok. </p> <@f.main.h3 title="Running delombok in ant" /> @@ -39,7 +41,7 @@ <javadoc sourcepath="build/src-delomboked" defaultexcludes="yes" destdir="build/api" /> </target></pre> <br /> - Instead of a <code>from</code> attribute, you can also nest <code><fileset></code> nodes. + Instead of a <code>from</code> attribute, you can also nest <code><fileset></code> nodes. The <code>delombok</code> supports <code>sourcepath</code>, <code>classpath</code>, and <code>modulepath</code> as parameter or as nested element, or as nested refid element, similar to the <code>javac</code> task. </p> <@f.main.h3 title="Running delombok in maven" /> diff --git a/website/templates/features/experimental/SuperBuilder.html b/website/templates/features/experimental/SuperBuilder.html index 8189a254..26f0a949 100644 --- a/website/templates/features/experimental/SuperBuilder.html +++ b/website/templates/features/experimental/SuperBuilder.html @@ -4,6 +4,8 @@ <@f.history> <p> <code>@SuperBuilder</code> was introduced as experimental feature in lombok v1.18.2. + </p><p> + <code>@SuperBuilder</code>'s <code>toBuilder</code> feature and limited support for customization was added with lombok v1.18.4. </p> </@f.history> @@ -11,7 +13,7 @@ <p> The <code>@SuperBuilder</code> annotation produces complex builder APIs for your classes. In contrast to <a href="/features/Builder"><code>@Builder</code></a>, <code>@SuperBuilder</code> also works with fields from superclasses. - However, it only works for types, and cannot be customized by providing a partial builder implementation. + However, it only works for types, and customization possibilities are limited. Most importantly, it requires that <em>all superclasses</em> also have the <code>@SuperBuilder</code> annotation. </p><p> <code>@SuperBuilder</code> lets you automatically produce the code required to have your class be instantiable with code such as:<br /> @@ -23,18 +25,25 @@ </p><p> <code>@SuperBuilder</code> is not compatible with <code>@Builder</code>. </p><p> + You can use <code>@SuperBuilder(toBuilder = true)</code> to also generate an instance method in your class called <code>toBuilder()</code>; it creates a new builder that starts out with all the values of this instance. You can put the <code>@Builder.ObtainVia</code> annotation on the fields to indicate alternative means by which the value for that field/parameter is obtained from this instance. For example, you can specify a method to be invoked: <code>@Builder.ObtainVia(method = "calculateFoo")</code>. + </p><p> To ensure type-safety, <code>@SuperBuilder</code> generates two inner builder classes for each annotated class, one abstract and one concrete class named <code><em>Foobar</em>Builder</code> and <code><em>Foobar</em>BuilderImpl</code> (where <em>Foobar</em> is the name of the annotated class). </p><p> + Customizing the code generated by <code>@SuperBuilder</code> is limited to adding new methods or annotations to the builder classes, and providing custom implementations of <code>builder()</code> and <code>build()</code>. + You have to make sure that the builder class declaration headers match those that would have been generated by lombok. Due to the heavy generics usage, we strongly advice to copy the builder class definition header from the uncustomized delomboked code. + </p><p> The configurable aspects of builder are: <ul> <li> The <em>build()</em> method's name (default: <code>"build"</code>) </li><li> The <em>builder()</em> method's name (default: <code>"builder"</code>) + </li><li> + If you want <code>toBuilder()</code> (default: no) </li> </ul> Example usage where all options are changed from their defaults:<br /> - <code>@SuperBuilder(buildMethodName = "execute", builderMethodName = "helloWorld")</code><br /> + <code>@SuperBuilder(buildMethodName = "execute", builderMethodName = "helloWorld", toBuilder = true)</code><br /> </p> </@f.overview> diff --git a/website/templates/setup/gwt.html b/website/templates/setup/gwt.html index ac6659a5..ce45fe7f 100644 --- a/website/templates/setup/gwt.html +++ b/website/templates/setup/gwt.html @@ -18,7 +18,7 @@ java <strong>-javaagent:lombok.jar=ECJ</strong> <em>(rest of arguments)</em> <p> To use the GWT plugin in eclipse together with Lombok:<br /> Install lombok into eclipse as normal (start <code>lombok.jar</code> as an application).<br /> - Download the JDT variant that GWT uses. This is the most recent org.eclipse.jdt.core_VERSION-CUSTOM-GWT jar found on the <a href="https://github.com/gwtproject/tools/tree/master/lib/eclipse">lib/eclipse section GWT's github page</a>. As of October 2018, that would be <a href="https://github.com/gwtproject/tools/raw/master/lib/eclipse/org.eclipse.jdt.core_3.13.50-CUSTOM-GWT-20171215.jar">org.eclipse.jdt.core_3.13.50-CUSTOM-GWT-20171215.jar</a>.<br /> + Download the JDT variant that GWT uses. For GWT v2.8.2 you'll need <a href="https://github.com/gwtproject/tools/raw/master/lib/eclipse/org.eclipse.jdt.core_3.11.2-CUSTOM-GWT-2.8-20160205.jar">org.eclipse.jdt.core 3.11.2</a>; for the current GWT development snapshot, this is <a href="https://github.com/gwtproject/tools/raw/master/lib/eclipse/org.eclipse.jdt.core_3.13.50-CUSTOM-GWT-20171215.jar">org.eclipse.jdt.core 3.13.50</a>. For more versions, search for jar files matching 'org.eclipse.jdt.core-{VERSION}-CUSTOM-GWT-{date}.jar in the <a href="https://github.com/gwtproject/tools/tree/master/lib/eclipse">lib/eclipse section GWT's github page</a>.<br /> Configure the 'GWT/Compile' option in the eclipse GWT plugin; in the advanced section, add the following VM arguments:<br /> <pre>-javaagent:/path/to/lombok.jar=ECJ -Xbootclasspath/p:/path/to/lombok.jar:/path/to/org.eclipse.jdt.core_fromPreviousStep.jar</pre> diff --git a/website/usageExamples/experimental/UtilityClassExample_post.jpage b/website/usageExamples/experimental/UtilityClassExample_post.jpage index 70810230..ad6cf583 100644 --- a/website/usageExamples/experimental/UtilityClassExample_post.jpage +++ b/website/usageExamples/experimental/UtilityClassExample_post.jpage @@ -5,7 +5,7 @@ public final class UtilityClassExample { throw new java.lang.UnsupportedOperationException("This is a utility class and cannot be instantiated"); } - public static void addSomething(int in) { + public static int addSomething(int in) { return in + CONSTANT; } } diff --git a/website/usageExamples/experimental/UtilityClassExample_pre.jpage b/website/usageExamples/experimental/UtilityClassExample_pre.jpage index 85731b81..3c33a7c6 100644 --- a/website/usageExamples/experimental/UtilityClassExample_pre.jpage +++ b/website/usageExamples/experimental/UtilityClassExample_pre.jpage @@ -4,7 +4,7 @@ import lombok.experimental.UtilityClass; public class UtilityClassExample { private final int CONSTANT = 5; - public void addSomething(int in) { + public int addSomething(int in) { return in + CONSTANT; } } |