diff options
Diffstat (limited to 'src/core/lombok/Builder.java')
| -rw-r--r-- | src/core/lombok/Builder.java | 87 |
1 files changed, 57 insertions, 30 deletions
diff --git a/src/core/lombok/Builder.java b/src/core/lombok/Builder.java index 9cf82191..7ae43bfa 100644 --- a/src/core/lombok/Builder.java +++ b/src/core/lombok/Builder.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2013-2014 The Project Lombok Authors. + * Copyright (C) 2013-2017 The Project Lombok Authors. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -48,8 +48,8 @@ import java.lang.annotation.Target; * as the relevant class, unless a method has been annotated, in which case it'll be equal to the * return type of that method. * <p> - * Complete documentation is found at <a href="https://projectlombok.org/features/experimental/Builder.html">the project lombok features page for @Builder</a>. - * <p> + * Complete documentation is found at <a href="https://projectlombok.org/features/Builder">the project lombok features page for @Builder</a>. + * <br> * <p> * Before: * @@ -107,10 +107,17 @@ import java.lang.annotation.Target; @Target({TYPE, METHOD, CONSTRUCTOR}) @Retention(SOURCE) public @interface Builder { - /** Name of the method that creates a new builder instance. Default: {@code builder}. */ + /** + * The field annotated with {@code @Default} must have an initializing expression; that expression is taken as the default to be used if not explicitly set during building. + */ + @Target(FIELD) + @Retention(SOURCE) + public @interface Default {} + + /** @return Name of the method that creates a new builder instance. Default: {@code builder}. */ String builderMethodName() default "builder"; - /** Name of the method in the builder class that creates an instance of your {@code @Builder}-annotated class. */ + /** @return Name of the method in the builder class that creates an instance of your {@code @Builder}-annotated class. */ String buildMethodName() default "build"; /** @@ -119,38 +126,50 @@ public @interface Builder { * Default for {@code @Builder} on types and constructors: {@code (TypeName)Builder}. * <p> * Default for {@code @Builder} on methods: {@code (ReturnTypeName)Builder}. + * + * @return Name of the builder class that will be generated (or if it already exists, will be filled with builder elements). */ String builderClassName() default ""; /** - * If true, the generated builder class will extend the {@code @Builder} of the - * superclass. In this way, the builder will also contain methods for fields - * from the superclass.<br> - * Note that both this builder and the superclass' builder must be a type - * {@code @Builder}; this feature does neither work for constructor nor - * method {@code @Builder}s. The parent {@code @Builder} must be - * {@link #extendable()}. <br> - * Implies {@link #extendable()}. + * Should the generated builder extend the parent class's builder? + * + * If {@code true}, the generated builder class will extend the builder of the + * superclass. This means the builder also contains the methods for fields from + * the superclass. + * <p> + * Note that both this builder and the superclass' builder must be a builder + * for a type (so, not for a static method or a constructor). You must mark + * the parent extendable: {@code @Builder(extensible = true)}. + * <p> + * This builder will also be {@code extensible = true} if you set {@code inherit = true}. + * + * @see #extensible() */ boolean inherit() default false; - + /** - * If true, the generated builder pattern will be extendable by - * {@code @Builder}s of subclasses, using the {@link #inherit()} feature. - * This is achieved by generating a special constructor that takes a builder - * instance as parameter (instead of an {@link AllArgsConstructor}). <br> - * Note that this builder must be a type {@code @Builder}; this feature does - * neither work for constructor nor method {@code @Builder}s.<br> - * If {@link #inherit()} {@code == true}, {@link #extendable()} will - * automatically be {@code true}. + * Should the generated builder be extensible by subclasses? + * + * If {@code true} the generated builder class will be extensible by + * {@code @Builder} classes of this class's subclasses, by marking them + * with {@code @Builder(inherit = true)}. + * <p> + * The {@code @Builder} extensible system only works for {@code @Builder} + * annotations on types (so, not on a static method or a constructor). + * + * @see #inherit() */ - boolean extendable() default false; - + boolean extensible() default false; + /** - * Name of the builder class in the superclass. Only relevant if - * {@code inherit = true} (see {@link #inherit()}). + * Name of the builder class in the superclass. + * + * Only relevant if {@code inherit = true} * - * Default {@code (SuperclassTypeName)Builder}. + * Default: {@code (SuperclassTypeName)Builder}. + * + * @see #inherit() */ String superclassBuilderClassName() default ""; @@ -158,6 +177,8 @@ public @interface Builder { * If true, generate an instance method to obtain a builder that is initialized with the values of this instance. * Legal only if {@code @Builder} is used on a constructor, on the type itself, or on a static method that returns * an instance of the declaring type. + * + * @return Whether to generate a {@code toBuilder()} method. */ boolean toBuilder() default false; @@ -174,13 +195,19 @@ public @interface Builder { @Target({FIELD, PARAMETER}) @Retention(SOURCE) public @interface ObtainVia { - /** Tells lombok to obtain a value with the expression {@code this.value}. */ + /** + * @return Tells lombok to obtain a value with the expression {@code this.value}. + */ String field() default ""; - /** Tells lombok to obtain a value with the expression {@code this.method()}. */ + /** + * @return Tells lombok to obtain a value with the expression {@code this.method()}. + */ String method() default ""; - /** Tells lombok to obtain a value with the expression {@code SelfType.method(this)}; requires {@code method} to be set. */ + /** + * @return Tells lombok to obtain a value with the expression {@code SelfType.method(this)}; requires {@code method} to be set. + */ boolean isStatic() default false; } } |