diff options
Diffstat (limited to 'src/core')
30 files changed, 201 insertions, 117 deletions
diff --git a/src/core/lombok/AllArgsConstructor.java b/src/core/lombok/AllArgsConstructor.java index 9bd60ea9..c059c65d 100644 --- a/src/core/lombok/AllArgsConstructor.java +++ b/src/core/lombok/AllArgsConstructor.java @@ -45,26 +45,33 @@ public @interface AllArgsConstructor { * is generated with the same argument list that wraps the real constructor. * * Such a static 'constructor' is primarily useful as it infers type arguments. + * + * @return Name of static 'constructor' method to generate (blank = generate a normal constructor). */ String staticName() default ""; /** * Any annotations listed here are put on the generated constructor. - * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br /> - * up to JDK7:<br /> - * {@code @AllArgsConstructor(onConstructor=@__({@AnnotationsGoHere}))}<br /> - * from JDK8:<br /> + * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br> + * up to JDK7:<br> + * {@code @AllArgsConstructor(onConstructor=@__({@AnnotationsGoHere}))}<br> + * from JDK8:<br> * {@code @AllArgsConstructor(onConstructor_={@AnnotationsGohere})} // note the underscore after {@code onConstructor}. + * + * @return List of annotations to apply to the generated constructor. */ AnyAnnotation[] onConstructor() default {}; /** * Sets the access level of the constructor. By default, generated constructors are {@code public}. + * + * @return The constructor will be generated with this access modifier. */ AccessLevel access() default lombok.AccessLevel.PUBLIC; /** * Placeholder annotation to enable the placement of annotations on the generated code. + * * @deprecated Don't use this annotation, ever - Read the documentation. */ @Deprecated diff --git a/src/core/lombok/Builder.java b/src/core/lombok/Builder.java index 07032432..af3c3c06 100644 --- a/src/core/lombok/Builder.java +++ b/src/core/lombok/Builder.java @@ -114,10 +114,10 @@ public @interface Builder { @Retention(SOURCE) public @interface Default {} - /** Name of the method that creates a new builder instance. Default: {@code builder}. */ + /** @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"; /** @@ -126,6 +126,8 @@ 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 ""; @@ -133,6 +135,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; @@ -149,13 +153,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; } } diff --git a/src/core/lombok/Cleanup.java b/src/core/lombok/Cleanup.java index c2430682..528855cd 100644 --- a/src/core/lombok/Cleanup.java +++ b/src/core/lombok/Cleanup.java @@ -72,6 +72,6 @@ import java.lang.annotation.Target; @Target(ElementType.LOCAL_VARIABLE) @Retention(RetentionPolicy.SOURCE) public @interface Cleanup { - /** The name of the method that cleans up the resource. By default, 'close'. The method must not have any parameters. */ + /** @return The name of the method that cleans up the resource. By default, 'close'. The method must not have any parameters. */ String value() default "close"; } diff --git a/src/core/lombok/ConfigurationKeys.java b/src/core/lombok/ConfigurationKeys.java index dec86aa7..90621027 100644 --- a/src/core/lombok/ConfigurationKeys.java +++ b/src/core/lombok/ConfigurationKeys.java @@ -261,7 +261,7 @@ public class ConfigurationKeys { // ----- NonNull ----- /** - * lombok configuration: {@code lombok.nonNull.exceptionType} = <String: <em>a java exception type; either [{@code IllegalArgumentException} or: {@code NullPointerException}]. + * lombok configuration: {@code lombok.nonNull.exceptionType} = <String: <em>a java exception type</em>; either [{@code IllegalArgumentException} or: {@code NullPointerException}]. * * Sets the exception to throw if {@code @NonNull} is applied to a method parameter, and a caller passes in {@code null}. */ @@ -466,7 +466,7 @@ public class ConfigurationKeys { * lombok configuration: {@code lombok.onX.flagUsage} = {@code WARNING} | {@code ERROR}. * * If set, <em>any</em> usage of {@code onX} results in a warning / error. - * <br /> + * <br> * Specifically, this flags usage of {@code @Getter(onMethod=...)}, {@code @Setter(onParam=...)}, {@code @Setter(onMethod=...)}, {@code @XArgsConstructor(onConstructor=...)}. */ public static final ConfigurationKey<FlagUsageType> ON_X_FLAG_USAGE = new ConfigurationKey<FlagUsageType>("lombok.onX.flagUsage", "Emit a warning or error if onX is used.") {}; diff --git a/src/core/lombok/Data.java b/src/core/lombok/Data.java index 8e55418b..ffa968c1 100644 --- a/src/core/lombok/Data.java +++ b/src/core/lombok/Data.java @@ -54,6 +54,8 @@ public @interface Data { * </pre> * * Default: No static constructor, instead the normal constructor is public. + * + * @return Name of static 'constructor' method to generate (blank = generate a normal constructor). */ String staticConstructor() default ""; } diff --git a/src/core/lombok/Delegate.java b/src/core/lombok/Delegate.java index f7c8b083..0c5a4c2c 100644 --- a/src/core/lombok/Delegate.java +++ b/src/core/lombok/Delegate.java @@ -40,6 +40,8 @@ public @interface Delegate { * type listed here is used only to determine which delegate methods to generate. * * NB: All methods in {@code Object}, as well as {@code canEqual(Object other)} will never be delegated. + * + * @return For each method (not already in {@code java.lang.Object}) in these types, generate a delegate method. */ Class<?>[] types() default {}; @@ -47,6 +49,8 @@ public @interface Delegate { * Each method in any of the types listed here (include supertypes) will <em>not</em> be delegated. * * NB: All methods in {@code Object}, as well as {@code canEqual(Object other)} will never be delegated. + * + * @return For each method (not already in {@code java.lang.Object}) in these types, skip generating a delegate method (overrides {@code types()}). */ Class<?>[] excludes() default {}; } diff --git a/src/core/lombok/EqualsAndHashCode.java b/src/core/lombok/EqualsAndHashCode.java index e249343c..2f88ac50 100644 --- a/src/core/lombok/EqualsAndHashCode.java +++ b/src/core/lombok/EqualsAndHashCode.java @@ -35,9 +35,10 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.SOURCE) public @interface EqualsAndHashCode { /** - * Any fields listed here will not be taken into account in the generated - * {@code equals} and {@code hashCode} implementations. + * Any fields listed here will not be taken into account in the generated {@code equals} and {@code hashCode} implementations. * Mutually exclusive with {@link #of()}. + * + * @return A list of fields to exclude. */ String[] exclude() default {}; @@ -46,30 +47,37 @@ public @interface EqualsAndHashCode { * Normally, all non-static, non-transient fields are used for identity. * <p> * Mutually exclusive with {@link #exclude()}. + * + * @return A list of fields to use (<em>default</em>: all of them). */ String[] of() default {}; /** - * Call on the superclass's implementations of {@code equals} and {@code hashCode} before calculating - * for the fields in this class. + * Call on the superclass's implementations of {@code equals} and {@code hashCode} before calculating for the fields in this class. * <strong>default: false</strong> + * + * @return Whether to call the superclass's {@code equals} implementation as part of the generated equals algorithm. */ boolean callSuper() default false; /** * Normally, if getters are available, those are called. To suppress this and let the generated code use the fields directly, set this to {@code true}. * <strong>default: false</strong> + * + * @return If {@code true}, always use direct field access instead of calling the getter method. */ boolean doNotUseGetters() default false; /** * Any annotations listed here are put on the generated parameter of {@code equals} and {@code canEqual}. - * This is useful to add for example a {@code Nullable} annotation.<br /> - * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br /> - * up to JDK7:<br /> - * {@code @EqualsAndHashCode(onParam=@__({@AnnotationsGoHere}))}<br /> - * from JDK8:<br /> + * This is useful to add for example a {@code Nullable} annotation.<br> + * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br> + * up to JDK7:<br> + * {@code @EqualsAndHashCode(onParam=@__({@AnnotationsGoHere}))}<br> + * from JDK8:<br> * {@code @EqualsAndHashCode(onParam_={@AnnotationsGohere})} // note the underscore after {@code onParam}. + * + * @return List of annotations to apply to the generated parameter in the {@code equals()} method. */ AnyAnnotation[] onParam() default {}; diff --git a/src/core/lombok/Getter.java b/src/core/lombok/Getter.java index f410eba7..5a23fe30 100644 --- a/src/core/lombok/Getter.java +++ b/src/core/lombok/Getter.java @@ -54,25 +54,29 @@ import java.lang.annotation.Target; public @interface Getter { /** * If you want your getter to be non-public, you can specify an alternate access level here. + * + * @return The getter method will be generated with this access modifier. */ lombok.AccessLevel value() default lombok.AccessLevel.PUBLIC; /** * Any annotations listed here are put on the generated method. - * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br /> - * up to JDK7:<br /> - * {@code @Getter(onMethod=@__({@AnnotationsGoHere}))}<br /> - * from JDK8:<br /> + * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br> + * up to JDK7:<br> + * {@code @Getter(onMethod=@__({@AnnotationsGoHere}))}<br> + * from JDK8:<br> * {@code @Getter(onMethod_={@AnnotationsGohere})} // note the underscore after {@code onMethod}. + * + * @return List of annotations to apply to the generated getter method. */ AnyAnnotation[] onMethod() default {}; boolean lazy() default false; /** - * Placeholder annotation to enable the placement of annotations on the generated code. - * @deprecated Don't use this annotation, ever - Read the documentation. - */ + * Placeholder annotation to enable the placement of annotations on the generated code. + * @deprecated Don't use this annotation, ever - Read the documentation. + */ @Deprecated @Retention(RetentionPolicy.SOURCE) @Target({}) diff --git a/src/core/lombok/Lombok.java b/src/core/lombok/Lombok.java index 6909f4fc..310b57e3 100644 --- a/src/core/lombok/Lombok.java +++ b/src/core/lombok/Lombok.java @@ -30,7 +30,6 @@ public class Lombok { * The exception is still thrown - javac will just stop whining about it. * <p> * Example usage: - * <p> * <pre>public void run() { * throw sneakyThrow(new IOException("You don't need to catch me!")); * }</pre> @@ -59,14 +58,13 @@ public class Lombok { } /** - * Returns the parameter directly. <br /> + * Returns the parameter directly. * - * This method can be used to prevent a static analyzer to determine - * the nullness of the passed parameter. + * This method can be used to prevent a static analyzer to determine the nullness of the passed parameter. * - * @param <T> the type of the parameter - * @param value the value to return - * @return value + * @param <T> the type of the parameter. + * @param value the value to return. + * @return value (this method just returns the parameter). */ public static <T> T preventNullAnalysis(T value) { return value; @@ -74,10 +72,12 @@ public class Lombok { /** * Ensures that the {@code value} is not {@code null}. - * @param value the value to test for null - * @param message the message of the {@link NullPointerException} - * @return the value if it is not null - * @throws NullPointerException with the {@code message} if the value is null + * + * @param <T> Type of the parameter. + * @param value the value to test for null. + * @param message the message of the {@link NullPointerException}. + * @return the value if it is not null. + * @throws NullPointerException with the {@code message} if the value is null. */ public static <T> T checkNotNull(T value, String message) { if (value == null) throw new NullPointerException(message); diff --git a/src/core/lombok/NoArgsConstructor.java b/src/core/lombok/NoArgsConstructor.java index 4eb61f93..672cd1c2 100644 --- a/src/core/lombok/NoArgsConstructor.java +++ b/src/core/lombok/NoArgsConstructor.java @@ -47,27 +47,35 @@ public @interface NoArgsConstructor { * is generated with the same argument list that wraps the real constructor. * * Such a static 'constructor' is primarily useful as it infers type arguments. + * + * @return Name of static 'constructor' method to generate (blank = generate a normal constructor). */ String staticName() default ""; /** * Any annotations listed here are put on the generated constructor. - * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br /> - * up to JDK7:<br /> - * {@code @NoArgsConstructor(onConstructor=@__({@AnnotationsGoHere}))}<br /> - * from JDK8:<br /> + * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br> + * up to JDK7:<br> + * {@code @NoArgsConstructor(onConstructor=@__({@AnnotationsGoHere}))}<br> + * from JDK8:<br> * {@code @NoArgsConstructor(onConstructor_={@AnnotationsGohere})} // note the underscore after {@code onConstructor}. + * + * @return List of annotations to apply to the generated constructor. */ AnyAnnotation[] onConstructor() default {}; /** * Sets the access level of the constructor. By default, generated constructors are {@code public}. + * + * @return The constructor will be generated with this access modifier. */ AccessLevel access() default lombok.AccessLevel.PUBLIC; /** * If {@code true}, initializes all final fields to 0 / null / false. * Otherwise, a compile time error occurs. + * + * @return Return {@code} true to force generation of a no-args constructor, picking defaults if necessary to assign required fields. */ boolean force() default false; diff --git a/src/core/lombok/RequiredArgsConstructor.java b/src/core/lombok/RequiredArgsConstructor.java index 0b3e7b14..f21bd647 100644 --- a/src/core/lombok/RequiredArgsConstructor.java +++ b/src/core/lombok/RequiredArgsConstructor.java @@ -45,21 +45,27 @@ public @interface RequiredArgsConstructor { * is generated with the same argument list that wraps the real constructor. * * Such a static 'constructor' is primarily useful as it infers type arguments. + * + * @return Name of static 'constructor' method to generate (blank = generate a normal constructor). */ String staticName() default ""; /** * Any annotations listed here are put on the generated constructor. - * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br /> - * up to JDK7:<br /> - * {@code @RequiredArgsConstructor(onConstructor=@__({@AnnotationsGoHere}))}<br /> - * from JDK8:<br /> + * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br> + * up to JDK7:<br> + * {@code @RequiredArgsConstructor(onConstructor=@__({@AnnotationsGoHere}))}<br> + * from JDK8:<br> * {@code @RequiredArgsConstructor(onConstructor_={@AnnotationsGohere})} // note the underscore after {@code onConstructor}. + * + * @return List of annotations to apply to the generated constructor. */ AnyAnnotation[] onConstructor() default {}; /** * Sets the access level of the constructor. By default, generated constructors are {@code public}. + * + * @return The constructor will be generated with this access modifier. */ AccessLevel access() default lombok.AccessLevel.PUBLIC; diff --git a/src/core/lombok/Setter.java b/src/core/lombok/Setter.java index 412a53f3..1b70bac9 100644 --- a/src/core/lombok/Setter.java +++ b/src/core/lombok/Setter.java @@ -55,26 +55,32 @@ import java.lang.annotation.Target; public @interface Setter { /** * If you want your setter to be non-public, you can specify an alternate access level here. + * + * @return The setter method will be generated with this access modifier. */ lombok.AccessLevel value() default lombok.AccessLevel.PUBLIC; /** * Any annotations listed here are put on the generated method. - * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br /> - * up to JDK7:<br /> - * {@code @Setter(onMethod=@__({@AnnotationsGoHere}))}<br /> - * from JDK8:<br /> + * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br> + * up to JDK7:<br> + * {@code @Setter(onMethod=@__({@AnnotationsGoHere}))}<br> + * from JDK8:<br> * {@code @Setter(onMethod_={@AnnotationsGohere})} // note the underscore after {@code onMethod}. + * + * @return List of annotations to apply to the generated setter method. */ AnyAnnotation[] onMethod() default {}; /** * Any annotations listed here are put on the generated method's parameter. - * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br /> - * up to JDK7:<br /> - * {@code @Setter(onParam=@__({@AnnotationsGoHere}))}<br /> - * from JDK8:<br /> + * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br> + * up to JDK7:<br> + * {@code @Setter(onParam=@__({@AnnotationsGoHere}))}<br> + * from JDK8:<br> * {@code @Setter(onParam_={@AnnotationsGohere})} // note the underscore after {@code onParam}. + * + * @return List of annotations to apply to the generated parameter in the setter method. */ AnyAnnotation[] onParam() default {}; diff --git a/src/core/lombok/Singular.java b/src/core/lombok/Singular.java index 655f2a9c..67edab96 100644 --- a/src/core/lombok/Singular.java +++ b/src/core/lombok/Singular.java @@ -29,10 +29,10 @@ import java.lang.annotation.Target; /** * The singular annotation is used together with {@code @Builder} to create single element 'add' methods in the builder for collections. - * <p> */ @Target({FIELD, PARAMETER}) @Retention(SOURCE) public @interface Singular { + /** @return The singular name of this field. If it's a normal english plural, lombok will figure it out automatically. Otherwise, this parameter is mandatory. */ String value() default ""; } diff --git a/src/core/lombok/SneakyThrows.java b/src/core/lombok/SneakyThrows.java index c94635d0..0506d615 100644 --- a/src/core/lombok/SneakyThrows.java +++ b/src/core/lombok/SneakyThrows.java @@ -59,8 +59,9 @@ import java.lang.annotation.Target; @Target({ElementType.METHOD, ElementType.CONSTRUCTOR}) @Retention(RetentionPolicy.SOURCE) public @interface SneakyThrows { - /** The exception type(s) you want to sneakily throw onward. */ + /** @return The exception type(s) you want to sneakily throw onward. */ Class<? extends Throwable>[] value() default java.lang.Throwable.class; - //The package is mentioned in java.lang due to a bug in javac (presence of an annotation processor throws off the type resolver for some reason). + //The fully qualified name is used for java.lang.Throwable in the parameter only. This works around a bug in javac: + // presence of an annotation processor throws off the type resolver for some reason. } diff --git a/src/core/lombok/Synchronized.java b/src/core/lombok/Synchronized.java index 6e75989a..5dff0fb2 100644 --- a/src/core/lombok/Synchronized.java +++ b/src/core/lombok/Synchronized.java @@ -43,6 +43,8 @@ public @interface Synchronized { /** * Optional: specify the name of a different field to lock on. It is a compile time error if this field * doesn't already exist (the fields are automatically generated only if you don't specify a specific name. + * + * @return Name of the field to lock on (blank = generate one). */ String value() default ""; } diff --git a/src/core/lombok/ToString.java b/src/core/lombok/ToString.java index c78866f4..18c3d9e3 100644 --- a/src/core/lombok/ToString.java +++ b/src/core/lombok/ToString.java @@ -37,12 +37,16 @@ public @interface ToString { /** * Include the name of each field when printing it. * <strong>default: true</strong> + * + * @return Whether or not to include the names of fields in the string produced by the generated {@code toString()}. */ boolean includeFieldNames() default true; /** * Any fields listed here will not be printed in the generated {@code toString} implementation. * Mutually exclusive with {@link #of()}. + * + * @return A list of fields to exclude. */ String[] exclude() default {}; @@ -51,18 +55,24 @@ public @interface ToString { * Normally, all non-static fields are printed. * <p> * Mutually exclusive with {@link #exclude()}. + * + * @return A list of fields to use (<em>default</em>: all of them). */ String[] of() default {}; /** * Include the result of the superclass's implementation of {@code toString} in the output. * <strong>default: false</strong> + * + * @return Whether to call the superclass's {@code equals} implementation as part of the generated equals algorithm. */ boolean callSuper() default false; /** * Normally, if getters are available, those are called. To suppress this and let the generated code use the fields directly, set this to {@code true}. * <strong>default: false</strong> + * + * @return If {@code true}, always use direct field access instead of calling the getter method. */ boolean doNotUseGetters() default false; } diff --git a/src/core/lombok/Value.java b/src/core/lombok/Value.java index 72b28857..562ba0cc 100644 --- a/src/core/lombok/Value.java +++ b/src/core/lombok/Value.java @@ -53,6 +53,8 @@ public @interface Value { * </pre> * * Default: No static constructor, instead the normal constructor is public. + * + * @return Name of static 'constructor' method to generate (blank = generate a normal constructor). */ String staticConstructor() default ""; } diff --git a/src/core/lombok/experimental/Accessors.java b/src/core/lombok/experimental/Accessors.java index 07c92159..dc9ae4b0 100644 --- a/src/core/lombok/experimental/Accessors.java +++ b/src/core/lombok/experimental/Accessors.java @@ -38,15 +38,19 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.SOURCE) public @interface Accessors { /** - * If true, accessors will be named after the field and not include a <code>get</code> or <code>set</code> - * prefix. If true and <code>chain</code> is omitted, <code>chain</code> defaults to <code>true</code>. + * If true, accessors will be named after the field and not include a {@code get} or {@code set} + * prefix. If true and {@code chain} is omitted, {@code chain} defaults to {@code true}. * <strong>default: false</strong> + * + * @return Whether or not to make fluent methods (named {@code fieldName()}, not for example {@code setFieldName}). */ boolean fluent() default false; /** - * If true, setters return <code>this</code> instead of <code>void</code>. - * <strong>default: false</strong>, unless <code>fluent=true</code>, then <strong>default: true</code> + * If true, setters return {@code this} instead of {@code void}. + * <strong>default: false</strong>, unless {@code fluent=true}, then <strong>default: true</strong> + * + * @return Whether or not setters should return themselves (chaining) or {@code void} (no chaining). */ boolean chain() default false; @@ -55,6 +59,8 @@ public @interface Accessors { * Note that a prefix only counts if the next character is NOT a lowercase character or the last * letter of the prefix is not a letter (for instance an underscore). If multiple fields * all turn into the same name when the prefix is stripped, an error will be generated. + * + * @return If you are in the habit of prefixing your fields (for example, you name them {@code fFieldName}, specify such prefixes here). */ String[] prefix() default {}; } diff --git a/src/core/lombok/experimental/Builder.java b/src/core/lombok/experimental/Builder.java index b5c14216..7b364bff 100644 --- a/src/core/lombok/experimental/Builder.java +++ b/src/core/lombok/experimental/Builder.java @@ -110,15 +110,20 @@ import java.lang.annotation.Target; @Retention(SOURCE) @Deprecated public @interface Builder { - /** Name of the method that creates a new builder instance. Default: {@code builder}. */ + /** @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"; - /** Name of the builder class. + /** + * Name of the builder class. + * * 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 ""; @@ -127,6 +132,8 @@ public @interface Builder { * to {@code false} to name the setter method for field {@code someField}: {@code setSomeField}. * <p> * <strong>Default: true</strong> + * + * @return Whether to generate fluent methods (just {@code fieldName()} instead of {@code setFieldName()}). */ boolean fluent() default true; @@ -135,6 +142,8 @@ public @interface Builder { * calls to set methods. Set this to {@code false} to have these 'set' methods return {@code void} instead. * <p> * <strong>Default: true</strong> + * + * @return Whether to generate chaining methods (each build call returns itself instead of returning {@code void}). */ boolean chain() default true; } diff --git a/src/core/lombok/experimental/Delegate.java b/src/core/lombok/experimental/Delegate.java index 3bf4419f..cc844526 100644 --- a/src/core/lombok/experimental/Delegate.java +++ b/src/core/lombok/experimental/Delegate.java @@ -52,6 +52,8 @@ public @interface Delegate { * type listed here is used only to determine which delegate methods to generate. * * NB: All methods in {@code Object}, as well as {@code canEqual(Object other)} will never be delegated. + * + * @return For each method (not already in {@code java.lang.Object}) in these types, generate a delegate method. */ Class<?>[] types() default {}; @@ -59,6 +61,8 @@ public @interface Delegate { * Each method in any of the types listed here (include supertypes) will <em>not</em> be delegated. * * NB: All methods in {@code Object}, as well as {@code canEqual(Object other)} will never be delegated. + * + * @return For each method (not already in {@code java.lang.Object}) in these types, skip generating a delegate method (overrides {@code types()}). */ Class<?>[] excludes() default {}; } diff --git a/src/core/lombok/experimental/ExtensionMethod.java b/src/core/lombok/experimental/ExtensionMethod.java index cdd0cf59..af38f6ed 100644 --- a/src/core/lombok/experimental/ExtensionMethod.java +++ b/src/core/lombok/experimental/ExtensionMethod.java @@ -60,12 +60,14 @@ import java.lang.annotation.*; @Target(TYPE) @Retention(SOURCE) public @interface ExtensionMethod { - /** All types whose static methods will be exposed as extension methods. */ + /** @return All types whose static methods will be exposed as extension methods. */ Class<?>[] value(); /** * If {@code true}, an applicable extension method is used (if found) even if the method call already was compilable (this is the default). * If {@code false}, an extension method is only used if the method call is not also defined by the type itself. + * + * @return Whether or not to override already existing methods with the extension. */ boolean suppressBaseMethods() default true; } diff --git a/src/core/lombok/experimental/Value.java b/src/core/lombok/experimental/Value.java index 9776681a..06dbee13 100644 --- a/src/core/lombok/experimental/Value.java +++ b/src/core/lombok/experimental/Value.java @@ -55,6 +55,8 @@ public @interface Value { * </pre> * * Default: No static constructor, instead the normal constructor is public. + * + * @return Name of static 'constructor' method to generate (blank = generate a normal constructor). */ String staticConstructor() default ""; } diff --git a/src/core/lombok/experimental/Wither.java b/src/core/lombok/experimental/Wither.java index 5ef50076..3df546d0 100644 --- a/src/core/lombok/experimental/Wither.java +++ b/src/core/lombok/experimental/Wither.java @@ -56,26 +56,32 @@ import lombok.AccessLevel; public @interface Wither { /** * If you want your wither to be non-public, you can specify an alternate access level here. + * + * @return The method will be generated with this access modifier. */ AccessLevel value() default AccessLevel.PUBLIC; /** * Any annotations listed here are put on the generated method. - * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br /> - * up to JDK7:<br /> - * {@code @Wither(onMethod=@__({@AnnotationsGoHere}))}<br /> - * from JDK8:<br /> + * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br> + * up to JDK7:<br> + * {@code @Wither(onMethod=@__({@AnnotationsGoHere}))}<br> + * from JDK8:<br> * {@code @Wither(onMethod_={@AnnotationsGohere})} // note the underscore after {@code onMethod}. + * + * @return List of annotations to apply to the generated method. */ AnyAnnotation[] onMethod() default {}; /** * Any annotations listed here are put on the generated method's parameter. - * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br /> - * up to JDK7:<br /> - * {@code @Wither(onParam=@__({@AnnotationsGoHere}))}<br /> - * from JDK8:<br /> + * The syntax for this feature depends on JDK version (nothing we can do about that; it's to work around javac bugs).<br> + * up to JDK7:<br> + * {@code @Wither(onParam=@__({@AnnotationsGoHere}))}<br> + * from JDK8:<br> * {@code @Wither(onParam_={@AnnotationsGohere})} // note the underscore after {@code onParam}. + * + * @return List of annotations to apply to the generated parameter in the method. */ AnyAnnotation[] onParam() default {}; diff --git a/src/core/lombok/extern/apachecommons/CommonsLog.java b/src/core/lombok/extern/apachecommons/CommonsLog.java index c89c7dca..04d5ef93 100644 --- a/src/core/lombok/extern/apachecommons/CommonsLog.java +++ b/src/core/lombok/extern/apachecommons/CommonsLog.java @@ -46,10 +46,10 @@ import java.lang.annotation.Target; * } * </pre> * - * This annotation is valid for classes and enumerations.<br /> + * This annotation is valid for classes and enumerations.<br> * - * @see org.apache.commons.logging.Log org.apache.commons.logging.Log - * @see org.apache.commons.logging.LogFactory#getLog(java.lang.Class) org.apache.commons.logging.LogFactory.getLog(Class target) + * @see <a href="https://commons.apache.org/proper/commons-logging/apidocs/org/apache/commons/logging/Log.html">org.apache.commons.logging.Log</a> + * @see <a href="https://commons.apache.org/proper/commons-logging/apidocs/org/apache/commons/logging/LogFactory.html#getLog(java.lang.Class)">org.apache.commons.logging.LogFactory#getLog(java.lang.Class)</a> * @see lombok.extern.java.Log @Log * @see lombok.extern.log4j.Log4j @Log4j * @see lombok.extern.log4j.Log4j2 @Log4j2 @@ -60,8 +60,6 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.SOURCE) @Target(ElementType.TYPE) public @interface CommonsLog { - /** - * Sets the category of the constructed Logger. By default, it will use the type where the annotation is placed. - */ + /** @return The category of the constructed Logger. By default, it will use the type where the annotation is placed. */ String topic() default ""; } diff --git a/src/core/lombok/extern/java/Log.java b/src/core/lombok/extern/java/Log.java index 3d50b88c..553b7c4a 100644 --- a/src/core/lombok/extern/java/Log.java +++ b/src/core/lombok/extern/java/Log.java @@ -46,9 +46,9 @@ import java.lang.annotation.Target; * } * </pre> * - * This annotation is valid for classes and enumerations.<br /> - * @see java.util.logging.Logger java.util.logging.Logger - * @see java.util.logging.Logger#getLogger(java.lang.String) java.util.logging.Logger.getLogger(String name) + * This annotation is valid for classes and enumerations.<br> + * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/util/logging/Logger.html">java.util.logging.Logger</a> + * @see <a href="https://docs.oracle.com/javase/8/docs/api/java/util/logging/Logger.html#getLogger-java.lang.String-">java.util.logging.Logger#getLogger(java.lang.String)</a> * @see lombok.extern.apachecommons.CommonsLog @CommonsLog * @see lombok.extern.log4j.Log4j @Log4j * @see lombok.extern.log4j.Log4j2 @Log4j2 @@ -59,8 +59,6 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.SOURCE) @Target(ElementType.TYPE) public @interface Log { - /** - * Sets the category of the constructed Logger. By default, it will use the type where the annotation is placed. - */ + /** @return The category of the constructed Logger. By default, it will use the type where the annotation is placed. */ String topic() default ""; } diff --git a/src/core/lombok/extern/jbosslog/JBossLog.java b/src/core/lombok/extern/jbosslog/JBossLog.java index 25bdd1d4..ea520aea 100644 --- a/src/core/lombok/extern/jbosslog/JBossLog.java +++ b/src/core/lombok/extern/jbosslog/JBossLog.java @@ -46,9 +46,9 @@ import java.lang.annotation.Target; * } * </pre> * - * This annotation is valid for classes and enumerations.<br /> - * @see org.jboss.logging.Logger org.jboss.logging.Logger - * @see org.jboss.logging.Logger#getLogger(java.lang.Class) org.jboss.logging.Logger.getLogger(Class target) + * This annotation is valid for classes and enumerations.<br> + * @see <a href="https://docs.jboss.org/jbosslogging/latest/org/jboss/logging/Logger.html">org.jboss.logging.Logger</a> + * @see <a href="https://docs.jboss.org/jbosslogging/latest/org/jboss/logging/Logger.html#getLogger(java.lang.Class)">org.jboss.logging.Logger#getLogger(java.lang.Class)</a> * @see lombok.extern.apachecommons.CommonsLog @CommonsLog * @see lombok.extern.java.Log @Log * @see lombok.extern.log4j.Log4j @Log4j @@ -59,9 +59,6 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.SOURCE) @Target(ElementType.TYPE) public @interface JBossLog { - - /** - * Sets the category of the constructed Logger. By default, it will use the type where the annotation is placed. - */ + /** @return The category of the constructed Logger. By default, it will use the type where the annotation is placed. */ String topic() default ""; } diff --git a/src/core/lombok/extern/log4j/Log4j.java b/src/core/lombok/extern/log4j/Log4j.java index ab03263e..ee719407 100644 --- a/src/core/lombok/extern/log4j/Log4j.java +++ b/src/core/lombok/extern/log4j/Log4j.java @@ -46,10 +46,10 @@ import java.lang.annotation.Target; * } * </pre> * - * This annotation is valid for classes and enumerations.<br /> + * This annotation is valid for classes and enumerations.<br> * - * @see org.apache.log4j.Logger org.apache.log4j.Logger - * @see org.apache.log4j.Logger#getLogger(java.lang.Class) org.apache.log4j.Logger.getLogger(Class target) + * @see <a href="https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Logger.html">org.apache.log4j.Logger</a> + * @see <a href="https://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Logger.html#getLogger(java.lang.Class)">org.apache.log4j.Logger#getLogger(java.lang.Class)</a> * @see lombok.extern.log4j.Log4j2 @Log4j2 * @see lombok.extern.apachecommons.CommonsLog @CommonsLog * @see lombok.extern.java.Log @Log @@ -60,8 +60,6 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.SOURCE) @Target(ElementType.TYPE) public @interface Log4j { - /** - * Sets the category of the constructed Logger. By default, it will use the type where the annotation is placed. - */ + /** @return The category of the constructed Logger. By default, it will use the type where the annotation is placed. */ String topic() default ""; } diff --git a/src/core/lombok/extern/log4j/Log4j2.java b/src/core/lombok/extern/log4j/Log4j2.java index 410244a9..4a5b166c 100644 --- a/src/core/lombok/extern/log4j/Log4j2.java +++ b/src/core/lombok/extern/log4j/Log4j2.java @@ -46,10 +46,10 @@ import java.lang.annotation.Target; * } * </pre> * - * This annotation is valid for classes and enumerations.<br /> + * This annotation is valid for classes and enumerations.<br> * - * @see org.apache.logging.log4j.Logger org.apache.logging.log4j.Logger - * @see org.apache.logging.log4j.LogManager#getLogger(java.lang.Class) org.apache.logging.log4j.LogManager.getLogger(Class target) + * @see <a href="https://logging.apache.org/log4j/2.x/log4j-api/apidocs/org/apache/logging/log4j/Logger.html">org.apache.logging.log4j.Logger</a> + * @see <a href="https://logging.apache.org/log4j/2.x/log4j-api/apidocs/org/apache/logging/log4j/LogManager.html#getLogger-java.lang.Class-">org.apache.logging.log4j.LogManager#getLogger(java.lang.Class)</a> * @see lombok.extern.log4j.Log4j @Log4j * @see lombok.extern.apachecommons.CommonsLog @CommonsLog * @see lombok.extern.java.Log @Log @@ -60,8 +60,6 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.SOURCE) @Target(ElementType.TYPE) public @interface Log4j2 { - /** - * Sets the category of the constructed Logger. By default, it will use the type where the annotation is placed. - */ + /** @return The category of the constructed Logger. By default, it will use the type where the annotation is placed. */ String topic() default ""; } diff --git a/src/core/lombok/extern/slf4j/Slf4j.java b/src/core/lombok/extern/slf4j/Slf4j.java index f7b1b9d5..24586d43 100644 --- a/src/core/lombok/extern/slf4j/Slf4j.java +++ b/src/core/lombok/extern/slf4j/Slf4j.java @@ -46,9 +46,9 @@ import java.lang.annotation.Target; * } * </pre> * - * This annotation is valid for classes and enumerations.<br /> - * @see org.slf4j.Logger org.slf4j.Logger - * @see org.slf4j.LoggerFactory#getLogger(java.lang.Class) org.slf4j.LoggerFactory.getLogger(Class target) + * This annotation is valid for classes and enumerations.<br> + * @see <a href="https://www.slf4j.org/api/org/slf4j/Logger.html">org.slf4j.Logger</a> + * @see <a href="https://www.slf4j.org/api/org/slf4j/LoggerFactory.html#getLogger(java.lang.Class)">org.slf4j.LoggerFactory#getLogger(java.lang.Class)</a> * @see lombok.extern.apachecommons.CommonsLog @CommonsLog * @see lombok.extern.java.Log @Log * @see lombok.extern.log4j.Log4j @Log4j @@ -59,9 +59,7 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.SOURCE) @Target(ElementType.TYPE) public @interface Slf4j { - /** - * Sets the category of the constructed Logger. By default, it will use the type where the annotation is placed. - */ + /** @return The category of the constructed Logger. By default, it will use the type where the annotation is placed. */ String topic() default ""; } diff --git a/src/core/lombok/extern/slf4j/XSlf4j.java b/src/core/lombok/extern/slf4j/XSlf4j.java index 66231c22..85a0fdd8 100644 --- a/src/core/lombok/extern/slf4j/XSlf4j.java +++ b/src/core/lombok/extern/slf4j/XSlf4j.java @@ -46,9 +46,9 @@ import java.lang.annotation.Target; * } * </pre> * - * This annotation is valid for classes and enumerations.<br /> - * @see org.slf4j.ext.XLogger org.slf4j.ext.XLogger - * @see org.slf4j.ext.XLoggerFactory#getLogger(java.lang.Class) org.slf4j.ext.XLoggerFactory.getXLogger(Class target) + * This annotation is valid for classes and enumerations.<br> + * @see <a href="https://www.slf4j.org/api/org/slf4j/ext/XLogger.html">org.slf4j.ext.XLogger</a> + * @see <a href="https://www.slf4j.org/api/org/slf4j/ext/XLoggerFactory.html#getXLogger(java.lang.Class)">org.slf4j.ext.XLoggerFactory#getLogger(java.lang.Class)</a> * @see lombok.extern.apachecommons.CommonsLog @CommonsLog * @see lombok.extern.java.Log @Log * @see lombok.extern.log4j.Log4j @Log4j @@ -59,8 +59,6 @@ import java.lang.annotation.Target; @Retention(RetentionPolicy.SOURCE) @Target(ElementType.TYPE) public @interface XSlf4j { - /** - * Sets the category of the constructed Logger. By default, it will use the type where the annotation is placed. - */ + /** @return The category of the constructed Logger. By default, it will use the type where the annotation is placed. */ String topic() default ""; } |