From ed61012f95cefae8d03260f506ffe34bc19bd90c Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Mon, 18 Feb 2013 21:41:07 +0100 Subject: [PATCH] whoops, belated push and fixes to the documentation of onX --- buildScripts/website.ant.xml | 6 +- .../{ => experimental}/onXExample_post.jpage | 0 .../{ => experimental}/onXExample_pre.jpage | 6 +- website/features/Constructor.html | 2 +- website/features/GetterSetter.html | 2 +- website/features/experimental/Value.html | 2 +- website/features/experimental/Wither.html | 2 +- website/features/experimental/index.html | 10 ++- website/features/experimental/onX.html | 88 +++++++++++++++++++ website/features/onX.html | 71 --------------- 10 files changed, 104 insertions(+), 85 deletions(-) rename usage_examples/{ => experimental}/onXExample_post.jpage (100%) rename usage_examples/{ => experimental}/onXExample_pre.jpage (65%) create mode 100644 website/features/experimental/onX.html delete mode 100644 website/features/onX.html diff --git a/buildScripts/website.ant.xml b/buildScripts/website.ant.xml index 35e34367..78dc8ed7 100644 --- a/buildScripts/website.ant.xml +++ b/buildScripts/website.ant.xml @@ -145,9 +145,6 @@ such as converting the changelog into HTML, and creating javadoc. - - - @@ -163,6 +160,9 @@ such as converting the changelog into HTML, and creating javadoc. + + + diff --git a/usage_examples/onXExample_post.jpage b/usage_examples/experimental/onXExample_post.jpage similarity index 100% rename from usage_examples/onXExample_post.jpage rename to usage_examples/experimental/onXExample_post.jpage diff --git a/usage_examples/onXExample_pre.jpage b/usage_examples/experimental/onXExample_pre.jpage similarity index 65% rename from usage_examples/onXExample_pre.jpage rename to usage_examples/experimental/onXExample_pre.jpage index 2cc9c581..fa03e2cd 100644 --- a/usage_examples/onXExample_pre.jpage +++ b/usage_examples/experimental/onXExample_pre.jpage @@ -7,9 +7,9 @@ import javax.persistence.Id; import javax.persistence.Column; import javax.validation.constraints.Max; -@AllArgsConstructor(onConstructor=@Inject) +@AllArgsConstructor(onConstructor=@_(@Inject)) public class OnXExample { - @Getter(onMethod={@Id, @Column(name="unique-id"}) - @Setter(onParam=@Max(10000)) + @Getter(onMethod=@_({@Id, @Column(name="unique-id")})) + @Setter(onParam=@_(@Max(10000))) private long unid; } diff --git a/website/features/Constructor.html b/website/features/Constructor.html index 051d730e..cdd5b4e2 100644 --- a/website/features/Constructor.html +++ b/website/features/Constructor.html @@ -35,7 +35,7 @@ Such a static factory method will infer generics, unlike a normal constructor. This means your API users get write MapEntry.of("foo", 5) instead of the much longer new MapEntry<String, Integer>("foo", 5).

- To put annotations on the generated constructor, you can use onConstructor={@AnnotationsHere}. For more details see the documentation on the onX feature. + To put annotations on the generated constructor, you can use onConstructor=@_({@AnnotationsHere}), but be careful; this is an experimental feature. For more details see the documentation on the onX feature.

Static fields are skipped by these annotations. Also, a @java.beans.ConstructorProperties annotation is added for all constructors with at least 1 argument, which allows bean editor tools to call the generated constructors. @ConstructorProperties is now in Java 1.6, which means that if your code is intended for diff --git a/website/features/GetterSetter.html b/website/features/GetterSetter.html index dde3456b..03704119 100644 --- a/website/features/GetterSetter.html +++ b/website/features/GetterSetter.html @@ -29,7 +29,7 @@ You can always manually disable getter/setter generation for any field by using the special AccessLevel.NONE access level. This lets you override the behaviour of a @Getter, @Setter or @Data annotation on a class.

- To put annotations on the generated method, you can use onMethod={@AnnotationsHere}; to put annotations on the only parameter of a generated setter method, you can use onParam={@AnnotationsHere}. For more details see the documentation on the onX feature. + To put annotations on the generated method, you can use onMethod=@_({@AnnotationsHere}); to put annotations on the only parameter of a generated setter method, you can use onParam=@_({@AnnotationsHere}). Be careful though! This is an experimental feature. For more details see the documentation on the onX feature.

diff --git a/website/features/experimental/Value.html b/website/features/experimental/Value.html index a82808e2..fb726d7b 100644 --- a/website/features/experimental/Value.html +++ b/website/features/experimental/Value.html @@ -68,7 +68,7 @@
- Back to experimental features | Previous feature (@Wither) | Next feature
+ Back to experimental features | Previous feature (@Wither) | Next feature (onX)
credits | Copyright © 2009-2013 The Project Lombok Authors, licensed under the MIT license.
diff --git a/website/features/experimental/Wither.html b/website/features/experimental/Wither.html index b0700aab..da2156cd 100644 --- a/website/features/experimental/Wither.html +++ b/website/features/experimental/Wither.html @@ -45,7 +45,7 @@ @Wither(level = AccessLevel.PROTECTED). Also like @Setter, you can also put a @Wither annotation on a type, which means a 'wither' is generated for each field (even non-final fields).

- To put annotations on the generated method, you can use onMethod={@AnnotationsHere}; to put annotations on the only parameter of this method, you can use onParam={@AnnotationsHere}. For more details see the documentation on the onX feature. + To put annotations on the generated method, you can use onMethod=@_({@AnnotationsHere}); to put annotations on the only parameter of a generated wither method, you can use onParam=@_({@AnnotationsHere}). Be careful though! This is an experimental feature. For more details see the documentation on the onX feature.

diff --git a/website/features/experimental/index.html b/website/features/experimental/index.html index acbbdbf6..24fbb541 100644 --- a/website/features/experimental/index.html +++ b/website/features/experimental/index.html @@ -24,14 +24,16 @@
@Accessors
A more fluent API for getters and setters.
-
@ExtensionMethod
+
@ExtensionMethod
Annoying API? Fix it yourself: Add new methods to existing types!
-
@FieldDefaults
+
@FieldDefaults
New default field modifiers for the 21st century.
-
@Wither
+
@Wither
Immutable 'setters' - methods that create a clone but with one changed field.
-
@Value
+
@Value
Immutable classes made very easy.
+
onMethod= / onConstructor= / onParam
+
Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you're annotating.
diff --git a/website/features/experimental/onX.html b/website/features/experimental/onX.html new file mode 100644 index 00000000..99365deb --- /dev/null +++ b/website/features/experimental/onX.html @@ -0,0 +1,88 @@ + + + + + + + + onX +
+
+
+
Project Lombok
+

onX

+
Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you're annotating.
+
+

Since

+

+ onX was introduced as experimental feature in lombok v0.11.7 (edge release only). +

+
+
+

Experimental

+

+ Experimental because: +

    +
  • Ugly syntax. The syntax of this feature is not optimal, but it is the least convoluted syntax that could possibly work (for now!)
    • +
  • Possibly java 9 will offer (much) better ways of supporting this feature.
    • +
  • Uncertainty: Future versions of javac may break this feature, and we may not be able to restore it.
    • +
+ Current status: uncertain - Currently we feel this feature cannot move out of experimental status. +
+
+

Overview

+

+ This feature is considered 'workaround status' - it exists in order to allow users of lombok that cannot work without this feature to have access to it anyway. If we find a better way to implement this feature, or some future java version introduces an alternative strategy, this feature can disappear without a reasonable deprecation period. Also, this feature may not work in future versions of javac. Use at your own discretion. +

+ Most annotations that make lombok generate methods or constructors can be configured to also make lombok put custom annotations on elements in the generated code. +

+ @Getter, @Setter, and @Wither support the onMethod option, which will put the listed annotations on the generated method. +

+ @AllArgsConstructor, @NoArgsConstructor, and @RequiredArgsConstructor support the onConstructor option which will put the listed annotations on the generated constructor. +

+ @Setter and @Wither support onParam in addition to onMethod; annotations listed will be put on the only parameter that the generated method has. +

+ The syntax is a little strange; to use any of the 3 onX features, you must wrap the annotations to be applied to the constructor / method / parameter in @_(@AnnotationGoesHere). To apply multiple annotations, use @_({@Annotation1, @Annotation2}). The annotations can themselves obviously have parameters as well. +

+
+
+
+

With Lombok

+
@HTML_PRE@
+
+
+
+

Vanilla Java

+
@HTML_POST@
+
+
+
+
+

Small print

+

+ The reason of the weird syntax is to make this feature work in javac 7 compilers; the @_ type is an annotation reference to the annotation type _ (underscore) which doesn't actually exist; this makes javac 7 delay aborting the compilation process due to an error because it is possible an annotation processor will later create the _ type. Instead, lombok applies the annotations and removes the references so that the error will never actually occur. The point is: The _ type must not exist, otherwise the feature does not work. In the rare case that the _ type does exist (and is imported or in the package), you can simply add more underscores. Technically any non-existent type would work, but to maintain consistency and readability and catch erroneous use, lombok considers it an error if the 'wrapper' annotation is anything but a series of underscores. +

+ To reiterate: This feature can disappear at any time; if you use this feature, be prepared to adjust your code when we find a nicer way of implementing this feature, or, if a future version of javac forces us to remove this feature entirely with no alternative. +

+ The onX parameter is not legal on any type-wide variant. For example, a @Getter annotation on a class does not support onMethod. +

+
+
+
+ Back to experimental features | Previous feature (@Value) | Next feature
+ credits | Copyright © 2009-2013 The Project Lombok Authors, licensed under the MIT license. +
+
+
+
+ + + diff --git a/website/features/onX.html b/website/features/onX.html deleted file mode 100644 index ab72e6f5..00000000 --- a/website/features/onX.html +++ /dev/null @@ -1,71 +0,0 @@ - - - - - - - - onX -
-
-
-
Project Lombok
-

onX

-
Sup dawg, we heard you like annotations, so we put annotations in your annotations so you can annotate while you're annotating.
-
-

Overview

-

- This feature is considered 'workaround status' - it exists in order to allow users of lombok that cannot work without this feature to have access to it anyway. If we find a better way to implement this feature, or some future java version introduces an alternative strategy, this feature can disappear without a reasonable deprecation period. Also, this feature may not work in future versions of javac. Use at your own discretion. -

- Most annotations that make lombok generate methods or constructors can be configured to also - make lombok put custom annotations on elements in the generated code. -

- @Getter, @Setter, and @Wither support the onMethod - option, which will put the listed annotations on the generated method. -

- @AllArgsConstructor, @NoArgsConstructor, and @RequiredArgsConstructor support the onConstructor option which will put the listed annotations on the generated constructor. -

- @Setter and @Wither support onParam in addition to onMethod; annotations listed will be put on the only parameter that the generated method has. -

- None of the mentioned annotations above actually have parameters named onMethod, onParam, or onConstructor; nevertheless, if you type them, lombok will make it work. Unfortunately this does mean that auto-complete and other tool-driven convenience features will not work as expected. The annotations lack these parameters in order to work around javac limitations. -

-
-
-
-

With Lombok

-
@HTML_PRE@
-
-
-
-

Vanilla Java

-
@HTML_POST@
-
-
-
-
-

Small print

-

- We can't think of any small print for this feature, other than to reiterate: This feature can disappear at any time; if you use this feature, be prepared to adjust your code when we find a nicer way of implementing this feature, or, if a future version of javac forces us to remove this feature entirely with no alternative. -

- The onX parameter is not legal on any type-wide variant. For example, a @Getter annotation on a class does not support onMethod. -

-
-
-
- Back to features
- credits | Copyright © 2009-2013 The Project Lombok Authors, licensed under the MIT license. -
-
-
-
- - -