Updated Delegate docs now that we've changed how it works (it no longer detects that you've implemented a few to-be delegated methods yourself).

3 files changed, 73 insertions, 50 deletions

diff --git a/usage_examples/DelegateExample_post.jpage b/usage_examples/DelegateExample_post.jpage
index 28c1bbb7..af2acc1a 100644
--- a/usage_examples/DelegateExample_post.jpage
+++ b/usage_examples/DelegateExample_post.jpage
@@ -2,15 +2,45 @@ import java.util.ArrayList;
 import java.util.Collection;
 import lombok.Delegate;
 
-public class DelegateExample {
+public class DelegationExample {
+	private interface SimpleCollection {
+		boolean add(String item);
+		boolean remove(Object item);
+	}
+	
+	@Delegate(types=SimpleCollection.class)
+	private final Collection<String> collection = new ArrayList<String>();
+	
+	@java.lang.SuppressWarnings("all")
+	public boolean add(final java.lang.String item) {
+		return this.collection.add(item);
+	}
 	
+	@java.lang.SuppressWarnings("all")
+	public boolean remove(final java.lang.Object item) {
+		return this.collection.remove(item);
+	}
+}
+
+class ExcludesDelegateExample {
 	long counter = 0L;
-	@Delegate
+	
+	private interface Add {
+		boolean add(String x);
+		boolean addAll(Collection<? extends String> x);
+	}
+	
+	@Delegate(excludes=Add.class)
 	private final Collection<String> collection = new ArrayList<String>();
 	
-	public boolean add(String name) {
+	public boolean add(String item) {
 		counter++;
-		return collection.add(name);
+		return collection.add(item);
+	}
+	
+	public boolean addAll(Collection<? extends String> col) {
+		counter += col.size();
+		return collection.addAll(col);
 	}
 	
 	@java.lang.SuppressWarnings("all")
@@ -54,11 +84,6 @@ public class DelegateExample {
 	}
 	
 	@java.lang.SuppressWarnings("all")
-	public boolean addAll(final java.util.Collection<? extends java.lang.String> arg0) {
-		return this.collection.addAll(arg0);
-	}
-	
-	@java.lang.SuppressWarnings("all")
 	public boolean removeAll(final java.util.Collection<?> arg0) {
 		return this.collection.removeAll(arg0);
 	}
@@ -73,26 +98,3 @@ public class DelegateExample {
 		this.collection.clear();
 	}
 }
-
-class PartialDelegationExample {
-	
-	@Delegate({SimpleCollection.class})
-	private final Collection<String> collection = new ArrayList<String>();
-	
-	private interface SimpleCollection {
-		
-		boolean add(String item);
-		
-		boolean remove(Object item);
-	}
-	
-	@java.lang.SuppressWarnings("all")
-	public boolean add(final java.lang.String item) {
-		return this.collection.add(item);
-	}
-	
-	@java.lang.SuppressWarnings("all")
-	public boolean remove(final java.lang.Object item) {
-		return this.collection.remove(item);
-	}
-}
\ No newline at end of file
diff --git a/usage_examples/DelegateExample_pre.jpage b/usage_examples/DelegateExample_pre.jpage
index b208c4ca..b6f05dfb 100644
--- a/usage_examples/DelegateExample_pre.jpage
+++ b/usage_examples/DelegateExample_pre.jpage
@@ -3,25 +3,35 @@ import java.util.Collection;
 
 import lombok.Delegate;
 
+public class DelegationExample {
+	private interface SimpleCollection {
+		boolean add(String item);
+		boolean remove(Object item);
+	}
+	
+	@Delegate(types=SimpleCollection.class)
+	private final Collection<String> collection = new ArrayList<String>();
+}
+
 
-public class DelegateExample {
+class ExcludesDelegateExample {
 	long counter = 0L;
 	
-	@Delegate
+	private interface Add {
+		boolean add(String x);
+		boolean addAll(Collection<? extends String> x);
+	}
+	
+	@Delegate(excludes=Add.class)
 	private final Collection<String> collection = new ArrayList<String>();
 	
-	public boolean add(String name) {
+	public boolean add(String item) {
 		counter++;
-		return collection.add(name);
+		return collection.add(item);
 	}
-}
-
-class PartialDelegationExample {
-	@Delegate({SimpleCollection.class})
-	private final Collection<String> collection = new ArrayList<String>();
 	
-	private interface SimpleCollection {
-		boolean add(String item);
-		boolean remove(Object item);
+	public boolean addAll(Collection<? extends String> col) {
+		counter += col.size();
+		return collection.addAll(col);
 	}
 }
diff --git a/website/features/Delegate.html b/website/features/Delegate.html
index 52b1035d..99f8a559 100644
--- a/website/features/Delegate.html
+++ b/website/features/Delegate.html
@@ -20,12 +20,21 @@
 			</p>
 			<p>
 			Lombok delegates all <code>public</code> methods of the field's type, as well as those of its supertype except for all methods declared 
-			in <code>java.lang.Object</code>. You can provide a specific implementation for a method by providing you own implementation, lombok will not
-			generate delegate methods for those already declared in the class.
+			in <code>java.lang.Object</code>.
 			</p>
 			<p>
-			You can pass any number of classes into the <code>@Delegate</code> annotation. If you do that, then lombok will delegate all <code>public</code>
-			methods in those types (and their supertypes, except <code>java.lang.Object</code>) instead of looking at the field's type.
+			You can pass any number of classes into the <code>@Delegate</code> annotation's <code>types</code> parameter.
+			If you do that, then lombok will delegate all <code>public</code> methods in those types (and their supertypes, except
+			<code>java.lang.Object</code>) instead of looking at the field's type.
+			</p>
+			<p>
+			All public non-Object methods that are part of the field's type (or, if you used <code>types</code> parameter, the methods of those types) are
+			copied, whether or not you also wrote implementations for those methods. That would thus result in duplicate method errors. You can avoid these
+			by using the <code>@Delegate(excludes=SomeType.class)</code> parameter to exclude all public methods in the excluded type(s), and their supertypes.
+			</p>
+			<p>
+			To have very precise control over what is delegated and what isn't, write private inner interfaces with method signatures, then specify these
+			private inner interfaces as types in <code>@Delegate(types=PrivateInnerInterfaceWithIncludesList.class, excludes=SameForExcludes.class)</code>.
 			</p>
 		</div>
 		<div class="snippets">
@@ -43,12 +52,14 @@
 		<div class="overview">
 			<h3>Small print</h3><div class="smallprint">
 			<p>
-			When passing classes to the annotation, these cannot contain generics. This is a limitation of java that lombok cannot work around.
+			When passing classes to the annotation's <code>types</code> or <code>excludes<code> parameter, you cannot include generics.
+			This is a limitation of java. Use private inner interfaces or classes that extend the intended type including the
+			generics parameter to work around this problem.
 			</p>
 			<p>
 			When passing classes to the annotation, these classes do not need to be supertypes of the field. See the example.
 			</p>
-			<div>	
+			<div>
 		</div>
 		<div class="footer">
 			<a href="index.html">Back to features</a> | <a href="val.html">Previous feature (val)</a> | <a href="onX.html">Next feature (onMethod=,onParameter=,onConstructor=)</a><br />