[fixes #2323] javadoc `@return` generation updated.

3 files changed, 19 insertions, 7 deletions

diff --git a/src/core/lombok/javac/handlers/HandleBuilder.java b/src/core/lombok/javac/handlers/HandleBuilder.java
index 11666048..1e8b8a22 100644
--- a/src/core/lombok/javac/handlers/HandleBuilder.java
+++ b/src/core/lombok/javac/handlers/HandleBuilder.java
@@ -819,7 +819,7 @@ 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);
+		copyJavadoc(originalFieldNode, newMethod, CopyJavadoc.SETTER, true);
 		
 		injectMethod(builderType, newMethod);
 	}
diff --git a/src/core/lombok/javac/handlers/HandleSetter.java b/src/core/lombok/javac/handlers/HandleSetter.java
index 926e94d9..9c7ce042 100644
--- a/src/core/lombok/javac/handlers/HandleSetter.java
+++ b/src/core/lombok/javac/handlers/HandleSetter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2009-2019 The Project Lombok Authors.
+ * Copyright (C) 2009-2020 The Project Lombok Authors.
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -279,7 +279,7 @@ public class HandleSetter extends JavacAnnotationHandler<Setter> {
 		
 		JCMethodDecl decl = recursiveSetGeneratedBy(treeMaker.MethodDef(treeMaker.Modifiers(access, annsOnMethod), methodName, methodType,
 			methodGenericParams, parameters, throwsClauses, methodBody, annotationMethodDefaultValue), source.get(), field.getContext());
-		copyJavadoc(field, decl, CopyJavadoc.SETTER);
+		copyJavadoc(field, decl, CopyJavadoc.SETTER, returnStatement != null);
 		return decl;
 	}
 }
diff --git a/src/core/lombok/javac/handlers/JavacHandlerUtil.java b/src/core/lombok/javac/handlers/JavacHandlerUtil.java
index c8fe5278..b3a5cf90 100644
--- a/src/core/lombok/javac/handlers/JavacHandlerUtil.java
+++ b/src/core/lombok/javac/handlers/JavacHandlerUtil.java
@@ -1962,7 +1962,7 @@ public class JavacHandlerUtil {
 		},
 		WITH {
 			@Override public String apply(final JCCompilationUnit cu, final JavacNode node) {
-				return applySetter(cu, node, "WITH|WITHER");
+				return addReturnsUpdatedSelfIfNeeded(applySetter(cu, node, "WITH|WITHER"));
 			}
 		};
 		
@@ -1992,6 +1992,9 @@ public class JavacHandlerUtil {
 		}
 	}
 	
+	public static void copyJavadoc(JavacNode from, JCTree to, CopyJavadoc copyMode) {
+		copyJavadoc(from, to, copyMode, false);
+	}
 	/**
 	 * Copies javadoc on one node to the other.
 	 * 
@@ -2001,12 +2004,15 @@ public class JavacHandlerUtil {
 	 * 
 	 * in 'SETTER' mode, stripping works similarly to 'GETTER' mode, except {@code param} are copied and stripped from the original and {@code @return} are skipped.
 	 */
-	public static void copyJavadoc(JavacNode from, JCTree to, CopyJavadoc copyMode) {
+	public static void copyJavadoc(JavacNode from, JCTree to, CopyJavadoc copyMode, boolean forceAddReturn) {
 		if (copyMode == null) copyMode = CopyJavadoc.VERBATIM;
 		try {
 			JCCompilationUnit cu = ((JCCompilationUnit) from.top().get());
 			String newJavadoc = copyMode.apply(cu, from);
-			if (newJavadoc != null) Javac.setDocComment(cu, to, newJavadoc);
+			if (newJavadoc != null) {
+				if (forceAddReturn) newJavadoc = addReturnsThisIfNeeded(newJavadoc);
+				Javac.setDocComment(cu, to, newJavadoc);
+			}
 		} catch (Exception ignore) {}
 	}
 	
@@ -2014,7 +2020,13 @@ public class JavacHandlerUtil {
 	static String addReturnsThisIfNeeded(String in) {
 		if (FIND_RETURN.matcher(in).find()) return in;
 		
-		return addJavadocLine(in, "@return this");
+		return addJavadocLine(in, "@return {@code this}.");
+	}
+	
+	static String addReturnsUpdatedSelfIfNeeded(String in) {
+		if (FIND_RETURN.matcher(in).find()) return in;
+		
+		return addJavadocLine(in, "@return a clone of this object, except with this updated property (returns {@code this} if an identical value is passed).");
 	}
 	
 	static String addJavadocLine(String in, String line) {