Documented @Delegate with javadoc.

2 files changed, 23 insertions, 2 deletions

diff --git a/src/core/lombok/Delegate.java b/src/core/lombok/Delegate.java
index 9056dada..4308f6f9 100644
--- a/src/core/lombok/Delegate.java
+++ b/src/core/lombok/Delegate.java
@@ -26,8 +26,27 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Put on any field to make lombok generate delegate methods that forward the call to this field.
+ * 
+ * Example:
+ * <pre>
+ *     private &#64;Delegate List&lt;String&gt; foo;
+ * </pre>
+ * 
+ * will generate for example an {@code boolean add(String)} method, which contains: {@code return foo.add(arg);}, as well as all other methods in {@code List}.
+ * 
+ * All public instance methods of the field's type, as well as all public instance methods of all the field's type's superfields are delegated, except for all methods
+ * that exist in {@link java.lang.Object}, and except for methods that are already present in the class.
+ */
 @Target(ElementType.FIELD)
 @Retention(RetentionPolicy.SOURCE)
 public @interface Delegate {
+	/**
+	 * Normally the type of the field is used as delegate type. However, to choose a different type to delegate, you can list one (or more) types here. Note that types with
+	 * type arguments can only be done as a field type. A solution for this is to create a private inner interface/class with the appropriate types extended, and possibly
+	 * with all methods you'd like to delegate listed, and then supply that class here. The field does not actually have to implement the type you're delegating; the
+	 * type listed here is used only to determine which delegate methods to generate.
+	 */
 	Class<?>[] value() default {};
 }
diff --git a/src/core/lombok/javac/handlers/HandleDelegate.java b/src/core/lombok/javac/handlers/HandleDelegate.java
index ad5eea16..73491770 100644
--- a/src/core/lombok/javac/handlers/HandleDelegate.java
+++ b/src/core/lombok/javac/handlers/HandleDelegate.java
@@ -54,7 +54,6 @@ import com.sun.tools.javac.code.Type.ClassType;
 import com.sun.tools.javac.code.Type.TypeVar;
 import com.sun.tools.javac.code.Types;
 import com.sun.tools.javac.model.JavacTypes;
-import com.sun.tools.javac.tree.JCTree;
 import com.sun.tools.javac.tree.JCTree.JCAnnotation;
 import com.sun.tools.javac.tree.JCTree.JCBlock;
 import com.sun.tools.javac.tree.JCTree.JCClassDecl;
@@ -89,7 +88,10 @@ public class HandleDelegate implements JavacAnnotationHandler<Delegate> {
 			"finalize()"));
 	
 	@Override public boolean handle(AnnotationValues<Delegate> annotation, JCAnnotation ast, JavacNode annotationNode) {
-		if (annotationNode.up().getKind() != Kind.FIELD) return false; // TODO error
+		if (annotationNode.up().getKind() != Kind.FIELD) {
+			// As the annotation is legal on fields only, javac itself will take care of printing an error message for this.
+			return false;
+		}
 		
 		List<Object> delegateTypes = annotation.getActualExpressions("value");
 		JavacResolution reso = new JavacResolution(annotationNode.getContext());