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.

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} = &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.") {};
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 {@