[fixes #2481] Copy constructor javadoc to builder methods

src/core/lombok/javac/handlers/HandleBuilder.java

@@ -27,6 +27,8 @@ import static lombok.javac.JavacTreeMaker.TypeTag.typeTag;
 import static lombok.javac.handlers.JavacHandlerUtil.*;
 
 import java.util.ArrayList;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 
 import javax.lang.model.element.Modifier;
 
@@ -38,6 +40,7 @@ import com.sun.tools.javac.tree.JCTree.JCAnnotation;
 import com.sun.tools.javac.tree.JCTree.JCArrayTypeTree;
 import com.sun.tools.javac.tree.JCTree.JCBlock;
 import com.sun.tools.javac.tree.JCTree.JCClassDecl;
+import com.sun.tools.javac.tree.JCTree.JCCompilationUnit;
 import com.sun.tools.javac.tree.JCTree.JCExpression;
 import com.sun.tools.javac.tree.JCTree.JCFieldAccess;
 import com.sun.tools.javac.tree.JCTree.JCIdent;
@@ -845,11 +848,30 @@ public class HandleBuilder extends JavacAnnotationHandler<Builder> {
 			newMethod.params = List.of(recv, newMethod.params.get(0));
 		}
 		recursiveSetGeneratedBy(newMethod, source.get(), builderType.getContext());
-		copyJavadoc(originalFieldNode, newMethod, CopyJavadoc.SETTER, true);
+		if (source.up().getKind() == Kind.METHOD) {
+			copyJavadocFromParam(originalFieldNode.up(), newMethod, paramName.toString());
+		} else {
+			copyJavadoc(originalFieldNode, newMethod, CopyJavadoc.SETTER, true);
+		}
 		
 		injectMethod(builderType, newMethod);
 	}
 	
+	private void copyJavadocFromParam(JavacNode from, JCMethodDecl to, String param) {
+		try {
+			JCCompilationUnit cu = ((JCCompilationUnit) from.top().get());
+			String methodComment = Javac.getDocComment(cu, from.get());
+			if (methodComment == null) return;
+			
+			Pattern pattern = Pattern.compile("@param " + param + " (\\S|\\s)+?(?=^ ?@)", Pattern.MULTILINE | Pattern.CASE_INSENSITIVE);
+			Matcher matcher = pattern.matcher(methodComment);
+			if (matcher.find()) {
+				String newJavadoc = addReturnsThisIfNeeded(matcher.group());
+				Javac.setDocComment(cu, to, newJavadoc);
+			}
+		} catch (Exception ignore) {}
+	}
+
 	public JavacNode makeBuilderClass(boolean isStatic, JavacNode source, JavacNode tdParent, String builderClassName, List<JCTypeParameter> typeParams, JCAnnotation ast, AccessLevel access) {
 		JavacTreeMaker maker = tdParent.getTreeMaker();
 		int modifiers = toJavacModifier(access);

test/transform/resource/after-delombok/BuilderConstructorJavadoc.java

@@ -0,0 +1,85 @@
+import java.util.List;
+
+class BuilderConstructorJavadoc<T> {
+	/**
+	 * This is a comment
+	 * 
+	 * @param basic tag is moved to the setter
+	 * @param multiline a param comment
+	 *        can be on multiple lines and can use 
+	 *        {@code @code} or <code>tags</code>
+	 * @param predef don't copy this one
+	 * @param predefWithJavadoc don't copy this one
+	 */
+	BuilderConstructorJavadoc(int basic, int multiline, int predef, int predefWithJavadoc) {
+	}
+
+
+	public static class BuilderConstructorJavadocBuilder<T> {
+		@java.lang.SuppressWarnings("all")
+		private int basic;
+		@java.lang.SuppressWarnings("all")
+		private int multiline;
+		@java.lang.SuppressWarnings("all")
+		private int predef;
+		@java.lang.SuppressWarnings("all")
+		private int predefWithJavadoc;
+
+		public BuilderConstructorJavadocBuilder<T> predef(final int x) {
+			this.predef = x;
+			return this;
+		}
+
+		/**
+		 * This javadoc remains untouched.
+		 * @param x 1/100 of the thing
+		 * @return the updated builder
+		 */
+		public BuilderConstructorJavadocBuilder<T> predefWithJavadoc(final int x) {
+			this.predefWithJavadoc = x;
+			return this;
+		}
+
+		@java.lang.SuppressWarnings("all")
+		BuilderConstructorJavadocBuilder() {
+		}
+
+		/**
+		 * @param basic tag is moved to the setter
+		 * @return {@code this}.
+		 */
+		@java.lang.SuppressWarnings("all")
+		public BuilderConstructorJavadoc.BuilderConstructorJavadocBuilder<T> basic(final int basic) {
+			this.basic = basic;
+			return this;
+		}
+
+		/**
+		 * @param multiline a param comment
+		 *        can be on multiple lines and can use 
+		 *        {@code @code} or <code>tags</code>
+		 * @return {@code this}.
+		 */
+		@java.lang.SuppressWarnings("all")
+		public BuilderConstructorJavadoc.BuilderConstructorJavadocBuilder<T> multiline(final int multiline) {
+			this.multiline = multiline;
+			return this;
+		}
+
+		@java.lang.SuppressWarnings("all")
+		public BuilderConstructorJavadoc<T> build() {
+			return new BuilderConstructorJavadoc<T>(this.basic, this.multiline, this.predef, this.predefWithJavadoc);
+		}
+
+		@java.lang.Override
+		@java.lang.SuppressWarnings("all")
+		public java.lang.String toString() {
+			return "BuilderConstructorJavadoc.BuilderConstructorJavadocBuilder(basic=" + this.basic + ", multiline=" + this.multiline + ", predef=" + this.predef + ", predefWithJavadoc=" + this.predefWithJavadoc + ")";
+		}
+	}
+
+	@java.lang.SuppressWarnings("all")
+	public static <T> BuilderConstructorJavadoc.BuilderConstructorJavadocBuilder<T> builder() {
+		return new BuilderConstructorJavadoc.BuilderConstructorJavadocBuilder<T>();
+	}
+}

test/transform/resource/after-ecj/BuilderConstructorJavadoc.java

@@ -0,0 +1,40 @@
+import java.util.List;
+class BuilderConstructorJavadoc<T> {
+  public static class BuilderConstructorJavadocBuilder<T> {
+    private @java.lang.SuppressWarnings("all") int basic;
+    private @java.lang.SuppressWarnings("all") int multiline;
+    private @java.lang.SuppressWarnings("all") int predef;
+    private @java.lang.SuppressWarnings("all") int predefWithJavadoc;
+    public BuilderConstructorJavadocBuilder<T> predef(final int x) {
+      this.predef = x;
+      return this;
+    }
+    public BuilderConstructorJavadocBuilder<T> predefWithJavadoc(final int x) {
+      this.predefWithJavadoc = x;
+      return this;
+    }
+    @java.lang.SuppressWarnings("all") BuilderConstructorJavadocBuilder() {
+      super();
+    }
+    public @java.lang.SuppressWarnings("all") BuilderConstructorJavadoc.BuilderConstructorJavadocBuilder<T> basic(final int basic) {
+      this.basic = basic;
+      return this;
+    }
+    public @java.lang.SuppressWarnings("all") BuilderConstructorJavadoc.BuilderConstructorJavadocBuilder<T> multiline(final int multiline) {
+      this.multiline = multiline;
+      return this;
+    }
+    public @java.lang.SuppressWarnings("all") BuilderConstructorJavadoc<T> build() {
+      return new BuilderConstructorJavadoc<T>(this.basic, this.multiline, this.predef, this.predefWithJavadoc);
+    }
+    public @java.lang.Override @java.lang.SuppressWarnings("all") java.lang.String toString() {
+      return (((((((("BuilderConstructorJavadoc.BuilderConstructorJavadocBuilder(basic=" + this.basic) + ", multiline=") + this.multiline) + ", predef=") + this.predef) + ", predefWithJavadoc=") + this.predefWithJavadoc) + ")");
+    }
+  }
+  @lombok.Builder BuilderConstructorJavadoc(int basic, int multiline, int predef, int predefWithJavadoc) {
+    super();
+  }
+  public static @java.lang.SuppressWarnings("all") <T>BuilderConstructorJavadoc.BuilderConstructorJavadocBuilder<T> builder() {
+    return new BuilderConstructorJavadoc.BuilderConstructorJavadocBuilder<T>();
+  }
+}

test/transform/resource/before/BuilderConstructorJavadoc.java

@@ -0,0 +1,35 @@
+import java.util.List;
+
+class BuilderConstructorJavadoc<T> {
+	/**
+	 * This is a comment
+	 * 
+	 * @param basic tag is moved to the setter
+	 * @param multiline a param comment
+	 *        can be on multiple lines and can use 
+	 *        {@code @code} or <code>tags</code>
+	 * @param predef don't copy this one
+	 * @param predefWithJavadoc don't copy this one
+	 */
+	@lombok.Builder
+	BuilderConstructorJavadoc(int basic, int multiline, int predef, int predefWithJavadoc) {
+		
+	}
+	
+	public static class BuilderConstructorJavadocBuilder<T> {
+		public BuilderConstructorJavadocBuilder<T> predef(final int x) {
+			this.predef = x;
+			return this;
+		}
+
+		/**
+		 * This javadoc remains untouched.
+		 * @param x 1/100 of the thing
+		 * @return the updated builder
+		 */
+		public BuilderConstructorJavadocBuilder<T> predefWithJavadoc(final int x) {
+			this.predefWithJavadoc = x;
+			return this;
+		}
+	}
+}