From 0038b48eeacac0389980902e65b4976dd5605c69 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Sun, 29 Jul 2018 17:17:22 +0200 Subject: docs for the redesigned FieldNameConstants. --- doc/changelog.markdown | 2 +- .../features/experimental/FieldNameConstants.html | 22 +++++++++++----------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/changelog.markdown b/doc/changelog.markdown index 0a12cb2d..238b4a38 100644 --- a/doc/changelog.markdown +++ b/doc/changelog.markdown @@ -2,7 +2,7 @@ Lombok Changelog ---------------- ### v1.18.3 "Edgy Guinea Pig" -* No changes yet. +* FEATURE: THe `@FieldNameConstants` feature has been completely redesigned. [Issue #1774](https://github.com/rzwitserloot/lombok/issues/1774) [FieldNameConstants documentation](https://projectlombok.org/features/experimental/FieldNameConstants) ### v1.18.2 (July 26th, 2018) * BUGFIX: mapstruct + lombok in eclipse should hopefully work again. [Issue #1359](https://github.com/rzwitserloot/lombok/issues/1359) and [mapstruct issue #1159](https://github.com/mapstruct/mapstruct/issues/1159) diff --git a/website/templates/features/experimental/FieldNameConstants.html b/website/templates/features/experimental/FieldNameConstants.html index c5e57195..a6fac99d 100644 --- a/website/templates/features/experimental/FieldNameConstants.html +++ b/website/templates/features/experimental/FieldNameConstants.html @@ -4,6 +4,8 @@ <@f.history>

@FieldNameConstants was introduced as experimental feature in lombok v1.16.22. +

+ @FieldNameConstants was redesigned in lombok v1.18.4.

@@ -18,11 +20,11 @@ <@f.overview>

- The @FieldNameConstants annotation generates string constants (fields marked public static final, of type java.lang.String) containing the field's name, as a string. This is useful for various marshalling and serialization frameworks. The constant field by default is named FIELD_NAME_OF_FIELD, where NAME_OF_FIELD is the same name as the field it represents, except with all uppercase letters, with underscores in front of the uppercase letters in the original field. The prefix (and suffix) is configurable on the @FieldNameConstants annotation. + The @FieldNameConstants annotation generates an inner type which contains 1 constant for each field in your class; either string constants (fields marked public static final, of type java.lang.String) or if you prefer, an enum type with 1 value for each field. @FieldNameConstants is useful for various marshalling and serialization frameworks. The constant field (whether enum value or string constant) always has the exact same name as the field, capitalization and all.

- The public access modifier can be changed via the parameter level = AccessLevel.PACKAGE for example. You can force a field to be skipped by supplying level = AccessLevel.NONE. + The generated inner type is by default called Fields and is public. You can modify this via @FieldNameConstants(innerTypeName = "FieldNames", access = AccessLevel.PACKAGE) for example. The default inner type name can also be modified via configuration key lombok.fieldNameConstants.innerTypeName. The generated fields are always public.

- Can be applied to classes (in which case every field gets a constant), or to an individual field. + Must be applied to classes (or enums, though you'd rarely want to do that). By default includes all non-transient, non-static fields. You can use @FieldNameConstants.Include in fields + @FieldNameConstants(onlyExplicitlyIncluded = true), or @FieldNameConstants.Exclude for more fine-grained control.

@@ -34,21 +36,19 @@
Lombok will flag any usage of @FieldDefaults as a warning or error if configured.
- lombok.fieldNameConstants.prefix = a string (default: 'PREFIX_') -
- Lombok will generate the name for each fieldconstant by constant-casing the field name and then prefixing this string to the result. -
- lombok.fieldNameConstants.suffix = a string (default: '' - the blank string) + lombok.fieldNameConstants.innerTypeName = a string (default: 'Fields')
- Lombok will generate the name for each fieldconstant by constant-casing the field name and then suffixing this string to the result. + The name of the inner type generated by lombok can be controlled with this configuration key.
<@f.smallPrint>

- Like other lombok handlers that touch fields, any field whose name starts with a dollar ($) symbol is skipped entirely. Such a field will not be modified at all. Static fields are also skipped. + From lombok v1.16.22 to lombok v1.18.2, this feature generated constants inside the type directly; the name of these fields would for example turn field exampleFieldName into public static final String FIELD_EXAMPLE_FIELD_NAME = "exampleFieldName";. The prefix and suffix (here, FIELD_, and the empty string) were configurable. Starting with lombok v1.18.4 this feature has been redesigned into generating an inner type as described above. +

+ Any parameters of lombok annotations that take strings need to be supplied actual string literals; you cannot have references to constants like those generated by @FieldNameConstants. If you'd like to use @FieldNameConstants to for example fill in the of and/or exclude parameters of @ToString and similar lombok annotations, use the @ToString.Include / @ToString.Exclude etc system instead; these are described at the feature pages for those features.

- The annotation can itself be used to set prefix/suffix. If you do so, it overrides the lombok.fieldNameConstants.prefix/suffix config key. Example: @FieldNameConstants(prefix = ""): This would generate for field helloWorld a constant named HELLO_WORLD instead of the default FIELD_HELLO_WORLD. + Like other lombok handlers that touch fields, any field whose name starts with a dollar ($) symbol is skipped entirely. Such a field will not be modified at all. Static fields are also skipped.

-- cgit