From e050dafc9016519e79184e383eab9ffbd579bebd Mon Sep 17 00:00:00 2001 From: Roel Spilker Date: Thu, 10 Jun 2021 22:25:23 +0200 Subject: Improve Builder documentation to emphasize the "builder()" factory method. Fixes #2870 --- website/resources/css/custom.css | 4 ++++ website/templates/features/Builder.html | 24 ++++++++++++++++++++---- 2 files changed, 24 insertions(+), 4 deletions(-) (limited to 'website') diff --git a/website/resources/css/custom.css b/website/resources/css/custom.css index ded02a06..240d6c4c 100644 --- a/website/resources/css/custom.css +++ b/website/resources/css/custom.css @@ -268,6 +268,10 @@ ol.snippet.cmd li:before { content: ">\A0\A0"; } +ol.snippet li.continued { + padding-left: 2em; +} + .fork-me { position: fixed; width: 150px; diff --git a/website/templates/features/Builder.html b/website/templates/features/Builder.html index 1b6c6e62..1461161f 100644 --- a/website/templates/features/Builder.html +++ b/website/templates/features/Builder.html @@ -21,9 +21,17 @@

The @Builder annotation produces complex builder APIs for your classes.

- @Builder lets you automatically produce the code required to have your class be instantiable with code such as:
- Person.builder().name("Adam Savage").city("San Francisco").job("Mythbusters").job("Unchained Reaction").build(); -

+ @Builder lets you automatically produce the code required to have your class be instantiable with code such as: +

+
    +
  1. Person.builder()
    2. +
  2. .name("Adam Savage")
    3. +
  3. .city("San Francisco")
    4. +
  4. .job("Mythbusters")
    5. +
  5. .job("Unchained Reaction")
    6. +
  6. .build();
    7. +
+

@Builder 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, @Builder is most easily explained with the "method" use-case.

A method annotated with @Builder (from now on called the target) causes the following 7 things to be generated: @@ -46,7 +54,15 @@ Each listed generated element will be silently skipped if that element already exists (disregarding parameter counts and looking only at names). This includes the builder itself: If that class already exists, lombok will simply start injecting fields and methods inside this already existing class, unless of course the fields / methods to be injected already exist. You may not put any other method (or constructor) generating lombok annotation on a builder class though; for example, you can not put @EqualsAndHashCode on the builder class.

- @Builder can generate so-called 'singular' methods for collection parameters/fields. These take 1 element instead of an entire list, and add the element to the list. For example: Person.builder().job("Mythbusters").job("Unchained Reaction").build(); would result in the List<String> jobs field to have 2 strings in it. To get this behavior, the field/parameter needs to be annotated with @Singular. The feature has its own documentation. + @Builder can generate so-called 'singular' methods for collection parameters/fields. These take 1 element instead of an entire list, and add the element to the list. For example: +

+
    +
  1. Person.builder()
    2. +
  2. .job("Mythbusters")
    3. +
  3. .job("Unchained Reaction")
    4. +
  4. .build();
    5. +
+

would result in the List<String> jobs field to have 2 strings in it. To get this behavior, the field/parameter needs to be annotated with @Singular. The feature has its own documentation.

Now that the "method" mode is clear, putting a @Builder 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.

-- cgit