Date: Thu, 22 May 2014 03:30:11 +0200 Subject: added documentation for the configuration feature. --- website/features/Cleanup.html | 7 ++ website/features/Constructor.html | 13 ++++ website/features/Data.html | 7 ++ website/features/EqualsAndHashCode.html | 9 +++ website/features/GetterLazy.html | 7 ++ website/features/GetterSetter.html | 15 ++++ website/features/Log.html | 25 +++++- website/features/NonNull.html | 7 ++ website/features/SneakyThrows.html | 7 ++ website/features/Synchronized.html | 7 ++ website/features/ToString.html | 11 +++ website/features/Value.html | 7 ++ website/features/configuration.html | 91 ++++++++++++++++++++++ website/features/experimental/Accessors.html | 13 ++++ website/features/experimental/Builder.html | 7 ++ website/features/experimental/Delegate.html | 7 ++ website/features/experimental/ExtensionMethod.html | 7 ++ website/features/experimental/FieldDefaults.html | 7 ++ website/features/experimental/Wither.html | 7 ++ website/features/experimental/index.html | 7 ++ website/features/features.css | 8 ++ website/features/index.html | 4 +- website/features/val.html | 7 ++ 23 files changed, 285 insertions(+), 2 deletions(-) create mode 100644 website/features/configuration.html diff --git a/website/features/Cleanup.html b/website/features/Cleanup.html index b5adff3a..f4b16946 100644 --- a/website/features/Cleanup.html +++ b/website/features/Cleanup.html @@ -40,6 +40,13 @@

Supported configuration keys:

lombok.cleanup.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Cleanup as a warning or error if configured.

Small print

diff --git a/website/features/Constructor.html b/website/features/Constructor.html index c7e40dfb..a3163bfa 100644 --- a/website/features/Constructor.html +++ b/website/features/Constructor.html @@ -60,6 +60,17 @@

Supported configuration keys:

lombok.anyConstructor.suppressConstructorProperties = [true | false] (default: false): If set to true, then lombok will skip adding a @java.beans.ConstructorProperties to generated constructors. This is useful in android and GWT development where that annotation is not usually available.
lombok.[allArgsConstructor|requiredArgsConstructor|noArgsConstructor].flagUsage = [warning | error] (default: not set): Lombok will flag any usage of the relevant annotation (@AllArgsConstructor, @RequiredArgsConstructor or @NoArgsConstructor) as a warning or error if configured.
lombok.anyConstructor.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of any of the 3 constructor-generating annotations as a warning or error if configured.

Small print

@@ -77,6 +88,8 @@ 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. +

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

diff --git a/website/features/Data.html b/website/features/Data.html index 8f11ca1c..3ae03df1 100644 --- a/website/features/Data.html +++ b/website/features/Data.html @@ -59,6 +59,13 @@

Supported configuration keys:

lombok.data.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Data as a warning or error if configured.

Small print

See the small print of @ToString, @EqualsAndHashCode, diff --git a/website/features/EqualsAndHashCode.html b/website/features/EqualsAndHashCode.html index f3fb8488..89d71502 100644 --- a/website/features/EqualsAndHashCode.html +++ b/website/features/EqualsAndHashCode.html @@ -54,6 +54,15 @@

Supported configuration keys:

lombok.equalsAndHashCode.doNotUseGetters = [true | false] (default: false): If set to true, lombok will access fields directly instead of using getters (if available) when generating equals and hashCode methods. The annotation parameter 'doNotUseGetters', if explicitly specified, takes precedence over this setting.
lombok.equalsAndHashCode.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @EqualsAndHashCode as a warning or error if configured.

Small print

diff --git a/website/features/GetterLazy.html b/website/features/GetterLazy.html index 3a711f58..a438f08a 100644 --- a/website/features/GetterLazy.html +++ b/website/features/GetterLazy.html @@ -30,6 +30,13 @@

Supported configuration keys (in addition to those listed on `@Getter`'s main page):

lombok.getter.lazy.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Getter(lazy=true) as a warning or error if configured.

Small print

diff --git a/website/features/GetterSetter.html b/website/features/GetterSetter.html index 76b61d80..a0da405d 100644 --- a/website/features/GetterSetter.html +++ b/website/features/GetterSetter.html @@ -46,6 +46,21 @@

Supported configuration keys:

lombok.accessors.chain = [true | false] (default: false): If set to true, generated setters will return this (instead of void). An explicitly configured chain parameter of an @Accessors annotation takes precedence over this setting.
lombok.accessors.fluent = [true | false] (default: false): If set to true, generated getters and setters will not be prefixed with the bean-standard 'get, is or set; instead, the methods will use the same name as the field (minus prefixes). An explicitly configured chain parameter of an @Accessors annotation takes precedence over this setting.
lombok.accessors.prefix += a field prefix (default: empty list): This is a list property; entries can be added with the += operator. Inherited prefixes from parent config files can be removed with the -= operator. Lombok will strip any matching field prefix from the name of a field in order to determine the name of the getter/setter to generate. For example, if m is one of the prefixes listed in this setting, then a field named mFoobar will result in a getter named getFoobar(), not getMFoobar(). An explicitly configured prefix parameter of an @Accessors annotation takes precedence over this setting.
lombok.setter.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Setter as a warning or error if configured.
lombok.getter.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Getter as a warning or error if configured.

Small print

diff --git a/website/features/Log.html b/website/features/Log.html index c459e7ff..8b635280 100644 --- a/website/features/Log.html +++ b/website/features/Log.html @@ -49,6 +49,29 @@

Supported configuration keys:

lombok.log.fieldName = an identifier (default: log): The generated logger fieldname is by default 'log', but you can change it to a different name with this setting.
lombok.log.fieldIsStatic = [true | false] (default: true): Normally the generated logger is a static field. By setting this key to false, the generated field will be an instance field instead.
lombok.log.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of any of the various log annotations as a warning or error if configured.
lombok.log.apacheCommons.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @lombok.extern.apachecommons.CommonsLog as a warning or error if configured.
lombok.log.javaUtilLogging.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @lombok.extern.java.Log as a warning or error if configured.
lombok.log.log4j.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @lombok.extern.log4j.Log4j as a warning or error if configured.
lombok.log.log4j2.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @lombok.extern.log4j.Log4j2 as a warning or error if configured.
lombok.log.slf4j.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @lombok.extern.slf4j.Slf4j as a warning or error if configured.
lombok.log.xslf4j.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @lombok.extern.slf4j.XSlf4j as a warning or error if configured.

Small print

@@ -59,7 +82,7 @@

diff --git a/website/features/NonNull.html b/website/features/NonNull.html index 9faad502..0e7d064d 100644 --- a/website/features/NonNull.html +++ b/website/features/NonNull.html @@ -39,6 +39,13 @@

Supported configuration keys:

lombok.nonNull.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @NonNull as a warning or error if configured.

Small print

diff --git a/website/features/SneakyThrows.html b/website/features/SneakyThrows.html index 875ee65c..e1cd6685 100644 --- a/website/features/SneakyThrows.html +++ b/website/features/SneakyThrows.html @@ -51,6 +51,13 @@

Supported configuration keys:

lombok.sneakyThrows.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @SneakyThrows as a warning or error if configured.

Small print

diff --git a/website/features/Synchronized.html b/website/features/Synchronized.html index c7e92aae..85c161c3 100644 --- a/website/features/Synchronized.html +++ b/website/features/Synchronized.html @@ -41,6 +41,13 @@

Supported configuration keys:

lombok.synchronized.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Synchronized as a warning or error if configured.

Small print

diff --git a/website/features/ToString.html b/website/features/ToString.html index ffda89d1..6cdd8453 100644 --- a/website/features/ToString.html +++ b/website/features/ToString.html @@ -41,6 +41,17 @@

Supported configuration keys:

lombok.toString.includeFieldNames = [true | false] (default: true): Normally lombok generates a fragment of the toString response for each field in the form of fieldName = fieldValue. If this setting is set to false, lombok will omit the name of the field and simply deploy a comma-separated list of all the field values. The annotation parameter 'includeFieldNames', if explicitly specified, takes precedence over this setting.
lombok.toString.doNotUseGetters = [true | false] (default: false): If set to true, lombok will access fields directly instead of using getters (if available) when generating toString methods. The annotation parameter 'doNotUseGetters', if explicitly specified, takes precedence over this setting.
lombok.toString.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @ToString as a warning or error if configured.

Small print

diff --git a/website/features/Value.html b/website/features/Value.html index 07e1e949..09557c6a 100644 --- a/website/features/Value.html +++ b/website/features/Value.html @@ -45,6 +45,13 @@

Supported configuration keys:

lombok.value.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Value as a warning or error if configured.

Small print

diff --git a/website/features/configuration.html b/website/features/configuration.html new file mode 100644 index 00000000..acf874e7 --- /dev/null +++ b/website/features/configuration.html @@ -0,0 +1,91 @@ + + + + + + + + Configuration system +

+ +

Configuration system

Lombok, made to order: Configure lombok features in one place for your entire project or even your workspace.

Overview

+ NEW in lombok 1.14: You can create lombok.config files in any directory and put configuration directives in it. These apply to all source files in this directory and all child directories.
+ The configuration system is particularly useful for configurable aspects of lombok which tend to be the same across an entire project, such as the name of your log variable. The configuration system can also be used to tell lombok to flag any usage of some lombok feature you don't like as a warning or even an error. +

+ Usually, a user of lombok puts a lombok.config file with their preferences in a workspace or project root directory, with the special config.stopBubbling = true key to tell lombok this is your root directory. You can then create lombok.config files in any subdirectories (generally representing projects or source packages) with different settings. +

+ An up to date list of all configuration keys supported by your version of lombok can be generated by running: +

java -jar lombok.jar config -g --verbose

+ The output of the config tool is itself a valid lombok.config file.
+ The config tool can also be used to display the complete lombok configuration used for any given directory or source file by supplying these as arguments. +

+ A sample of available configuration options (see the feature pages of the lombok features for their related config keys, as well as java -jar lombok.jar config -g for the complete list): +

lombok.accessors.chain: If set to true, generated setters will 'chain' by default (They will return this instead of having a void return type).
lombok.accessors.fluent: If set to true, generated setters and getters will simply be named the same as the field name, without a get or set prefix.
lombok.anyConstructor.suppressConstructorProperties: If true, lombok will not generate a @java.beans.ConstructorProperties annotation when generating constructors. This is particularly useful for GWT and Android development.
lombok.log.fieldName: The name of the generated log field (default: log).
lombok.(featureName).flagUsage: Allows you to forcibly stop or discourage use of a lombok feature. Legal values for this key are warning or error. Some examples of values for (featureName) are: "experimental" (flags use of any of the experimental features), "builder", "sneakyThrows", or "extensionMethod".

+ Configuration files are hierarchical: Any configuration setting applies to all source files in that directory, and all source files in subdirectories, but configuration settings closer to the source file take precedence. For example, if you have in /Users/me/projects/lombok.config the following: +

+ lombok.log.fieldName = foobar +

+ and in /Users/me/projects/MyProject/lombok.config you have: +

+ lombok.log.fieldName = xyzzy +

+ + Then the various @Log annotations will use foobar instead of the default log as a field name to generate in all your projects, + except for your project in /Users/me/projects/MyProject, where xyzzy is used instead. +

+ To restore a configuration key set by a parent config file back to the default, the clear option can be used. For example, if a parent configuration file has configured all use of val to emit a warning, you can turn off the warnings for a subdirectory by including in it a lombok.config file with: +

+ clear lombok.val.flagUsage +

+ Some configuration keys take lists. For lists, use += to add an entry. You can remove a single item from the list (useful to undo a parent configuration file's setting) with -=. For example: +

+ lombok.accessors.prefix += m_ +

+ To stop lombok from looking at parent directories for more configuration files, the special key: +

+ config.stopBubbling = true +

+ can be included. +

+ Comments can be included in lombok.config files; any line that starts with # is considered a comment. +

+ +

+ + + diff --git a/website/features/experimental/Accessors.html b/website/features/experimental/Accessors.html index 79c3d272..20590a07 100644 --- a/website/features/experimental/Accessors.html +++ b/website/features/experimental/Accessors.html @@ -72,6 +72,19 @@

Supported configuration keys:

lombok.accessors.chain = [true | false] (default: false): If set to true, any class that either doesn't have an @Accessors annotation, or it does, but that annotation does not have an explicit value for the chain parameter, will act as if @Accessors(chain = true) is present.
lombok.accessors.fluent = [true | false] (default: false): If set to true, any class that either doesn't have an @Accessors annotation, or it does, but that annotation does not have an explicit value for the fluent parameter, will act as if @Accessors(fluent = true) is present.
lombok.accessors.prefix += a field prefix (default: empty list): This is a list property; entries can be added with the += operator. Inherited prefixes from parent config files can be removed with the -= operator. Any class that either doesn't have an @Accessors annotation, or it does, but that annotation does not have an explicit value for the prefix parameter, will act as if @Accessors(prefix = {prefixes listed in configuration}) is present.
lombok.accessors.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Accessors as a warning or error if configured.

Small print

diff --git a/website/features/experimental/Builder.html b/website/features/experimental/Builder.html index 84452299..a8e21b9a 100644 --- a/website/features/experimental/Builder.html +++ b/website/features/experimental/Builder.html @@ -91,6 +91,13 @@

Supported configuration keys:

lombok.builder.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Builder as a warning or error if configured.

Small print

diff --git a/website/features/experimental/Delegate.html b/website/features/experimental/Delegate.html index 41a36d82..bd4fc393 100644 --- a/website/features/experimental/Delegate.html +++ b/website/features/experimental/Delegate.html @@ -59,6 +59,13 @@

Supported configuration keys:

lombok.delegate.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Delegate as a warning or error if configured.

Small print

diff --git a/website/features/experimental/ExtensionMethod.html b/website/features/experimental/ExtensionMethod.html index b2c751b9..58aaf1b3 100644 --- a/website/features/experimental/ExtensionMethod.html +++ b/website/features/experimental/ExtensionMethod.html @@ -77,6 +77,13 @@ System.out.println(x.or("Hello, World!"));

Supported configuration keys:

lombok.extensionMethod.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @ExtensionMethod as a warning or error if configured.

Small print

diff --git a/website/features/experimental/FieldDefaults.html b/website/features/experimental/FieldDefaults.html index 159938a5..12ea7d80 100644 --- a/website/features/experimental/FieldDefaults.html +++ b/website/features/experimental/FieldDefaults.html @@ -56,6 +56,13 @@

Supported configuration keys:

lombok.fieldDefaults.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @FieldDefaults as a warning or error if configured.

Small print

diff --git a/website/features/experimental/Wither.html b/website/features/experimental/Wither.html index 12475f6e..9ca43a46 100644 --- a/website/features/experimental/Wither.html +++ b/website/features/experimental/Wither.html @@ -62,6 +62,13 @@

Supported configuration keys:

lombok.wither.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of @Wither as a warning or error if configured.

Small print

diff --git a/website/features/experimental/index.html b/website/features/experimental/index.html index 2c641228..f37712e0 100644 --- a/website/features/experimental/index.html +++ b/website/features/experimental/index.html @@ -38,6 +38,13 @@

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

Supported configuration keys:

lombok.experimental.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of any of the features listed here as a warning or error if configured.

Putting the "Ex" in "Experimental": promoted or deleted experimental features.

Laziness is a virtue!
@Log: Captain's Log, stardate 24435.7: "What was that line again?"
experimental features
Configuration system: Lombok, made to order: Configure lombok features in one place for your entire project or even your workspace.
Experimental features: Here be dragons: Extra features which aren't quite ready for prime time yet.

diff --git a/website/features/val.html b/website/features/val.html index c4c8ad27..84158d27 100644 --- a/website/features/val.html +++ b/website/features/val.html @@ -38,6 +38,13 @@

Supported configuration keys:

lombok.val.flagUsage = [warning | error] (default: not set): Lombok will flag any usage of val as a warning or error if configured.

Small print

-- cgit

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys (in addition to those listed on @Getter's main page):

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Configuration system

Overview

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Small print

Supported configuration keys:

Putting the "Ex" in "Experimental": promoted or deleted experimental features.

Supported configuration keys:

Small print

Supported configuration keys (in addition to those listed on `@Getter`'s main page):