Javadoc now builds without warnings. All links to external javadoc replaced with straight up links to avoid the <javadoc> target from trying to download a bunch of index pages.

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

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;
 	}
 }

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";
 }

src/core/lombok/ConfigurationKeys.java

@@ -261,7 +261,7 @@ public class ConfigurationKeys {
 	// ----- NonNull -----
 	
 	/**
-	 * lombok configuration: {@code lombok.nonNull.exceptionType} = &lt;String: <em>a java exception type; either [{@code IllegalArgumentException} or: {@code NullPointerException}].
+	 * lombok configuration: {@code lombok.nonNull.exceptionType} = &lt;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.") {};

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 "";
 }

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 {};
 }

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 {};
 	

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({})

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);

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;
 	

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;
 	

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 {};
 	

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 "";
 }

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.
 }

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 "";
 }

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;
 }

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 "";
 }

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 {};
 }

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;
 }

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 {};
 }

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;
 }

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 "";
 }

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 {};
 	

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 &#64;Log
  * @see lombok.extern.log4j.Log4j &#64;Log4j
  * @see lombok.extern.log4j.Log4j2 &#64;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 "";
 }

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 &#64;CommonsLog
  * @see lombok.extern.log4j.Log4j &#64;Log4j
  * @see lombok.extern.log4j.Log4j2 &#64;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 "";
 }

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 &#64;CommonsLog
  * @see lombok.extern.java.Log &#64;Log
  * @see lombok.extern.log4j.Log4j &#64;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 "";
 }

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 &#64;Log4j2
  * @see lombok.extern.apachecommons.CommonsLog &#64;CommonsLog
  * @see lombok.extern.java.Log &#64;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 "";
 }

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 &#64;Log4j
  * @see lombok.extern.apachecommons.CommonsLog &#64;CommonsLog
  * @see lombok.extern.java.Log &#64;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 "";
 }

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 &#64;CommonsLog
  * @see lombok.extern.java.Log &#64;Log
  * @see lombok.extern.log4j.Log4j &#64;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 "";
 }
 

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 &#64;CommonsLog
  * @see lombok.extern.java.Log &#64;Log
  * @see lombok.extern.log4j.Log4j &#64;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 "";
 }