When generating javadoc for setters, a @return this is added if needed.

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

@@ -1485,6 +1485,18 @@ public class JavacHandlerUtil {
 		} catch (Exception ignore) {}
 	}
 	
+	private static final Pattern FIND_RETURN = Pattern.compile("^\\s*\\**\\s*@returns?\\s+.*$", Pattern.MULTILINE | Pattern.CASE_INSENSITIVE);
+	static String addReturnsThisIfNeeded(String in) {
+		if (FIND_RETURN.matcher(in).find()) return in;
+		
+		return addJavadocLine(in, "@return this");
+	}
+	
+	static String addJavadocLine(String in, String line) {
+		if (in.endsWith("\n")) return in + line + "\n";
+		return in + "\n" + line;
+	}
+	
 	private static class CopyJavadoc_8 {
 		static void copyJavadoc(JavacNode from, JCTree to, CopyJavadoc copyMode, Object dc) {
 			DocCommentTable dct = (DocCommentTable) dc;
@@ -1492,6 +1504,9 @@ public class JavacHandlerUtil {
 			
 			if (javadoc != null) {
 				String[] filtered = copyMode.split(javadoc.getText());
+				if (copyMode == CopyJavadoc.SETTER && shouldReturnThis(from)) {
+					filtered[0] = addReturnsThisIfNeeded(filtered[0]);
+				}
 				dct.putComment(to, createJavadocComment(filtered[0], from));
 				dct.putComment(from.get(), createJavadocComment(filtered[1], from));
 			}
@@ -1525,6 +1540,9 @@ public class JavacHandlerUtil {
 		
 		if (javadoc != null) {
 			String[] filtered = copyMode.split(javadoc);
+			if (copyMode == CopyJavadoc.SETTER && shouldReturnThis(from)) {
+				filtered[0] = addReturnsThisIfNeeded(filtered[0]);
+			}
 			docComments.put(to, filtered[0]);
 			docComments.put(from.get(), filtered[1]);
 		}

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

@@ -108,4 +108,58 @@ class GetterSetterJavadoc3 {
 	public void setFieldName(final int fieldName) {
 		this.fieldName = fieldName;
 	}
-}
+}
+class GetterSetterJavadoc4 {
+	/**
+	 * Some text
+	 */
+	private int fieldName;
+	/**
+	 * Some text
+	 * 
+	 * @return Sky is blue4
+	 */
+	@java.lang.SuppressWarnings("all")
+	@javax.annotation.Generated("lombok")
+	public int fieldName() {
+		return this.fieldName;
+	}
+	/**
+	 * Some text
+	 * 
+	 * @param fieldName Hello, World5
+	 * @return this
+	 */
+	@java.lang.SuppressWarnings("all")
+	@javax.annotation.Generated("lombok")
+	public GetterSetterJavadoc4 fieldName(final int fieldName) {
+		this.fieldName = fieldName;
+		return this;
+	}
+}
+class GetterSetterJavadoc5 {
+	/**
+	 * Some text
+	 */
+	private int fieldName;
+	/**
+	 * Getter section
+	 * @return Sky is blue5
+	 */
+	@java.lang.SuppressWarnings("all")
+	@javax.annotation.Generated("lombok")
+	public int fieldName() {
+		return this.fieldName;
+	}
+	/**
+	 * Setter section
+	 * @param fieldName Hello, World5
+	 * @return Sky is blue5
+	 */
+	@java.lang.SuppressWarnings("all")
+	@javax.annotation.Generated("lombok")
+	public GetterSetterJavadoc5 fieldName(final int fieldName) {
+		this.fieldName = fieldName;
+		return this;
+	}
+}

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

@@ -57,4 +57,30 @@ class GetterSetterJavadoc3 {
   public @java.lang.SuppressWarnings("all") @javax.annotation.Generated("lombok") void setFieldName(final int fieldName) {
     this.fieldName = fieldName;
   }
+}
+@lombok.experimental.Accessors(chain = true,fluent = true) class GetterSetterJavadoc4 {
+  private @lombok.Getter @lombok.Setter int fieldName;
+  GetterSetterJavadoc4() {
+    super();
+  }
+  public @java.lang.SuppressWarnings("all") @javax.annotation.Generated("lombok") int fieldName() {
+    return this.fieldName;
+  }
+  public @java.lang.SuppressWarnings("all") @javax.annotation.Generated("lombok") GetterSetterJavadoc4 fieldName(final int fieldName) {
+    this.fieldName = fieldName;
+    return this;
+  }
+}
+@lombok.experimental.Accessors(chain = true,fluent = true) class GetterSetterJavadoc5 {
+  private @lombok.Getter @lombok.Setter int fieldName;
+  GetterSetterJavadoc5() {
+    super();
+  }
+  public @java.lang.SuppressWarnings("all") @javax.annotation.Generated("lombok") int fieldName() {
+    return this.fieldName;
+  }
+  public @java.lang.SuppressWarnings("all") @javax.annotation.Generated("lombok") GetterSetterJavadoc5 fieldName(final int fieldName) {
+    this.fieldName = fieldName;
+    return this;
+  }
 }

test/transform/resource/before/GetterSetterJavadoc.java

@@ -35,3 +35,30 @@ class GetterSetterJavadoc3 {
 	 */
 	@lombok.Getter @lombok.Setter private int fieldName;
 }
+
+@lombok.experimental.Accessors(chain = true, fluent = true)
+class GetterSetterJavadoc4 {
+	/**
+	 * Some text
+	 *
+	 * @param fieldName Hello, World4
+	 * @return Sky is blue4
+	 */
+	@lombok.Getter @lombok.Setter private int fieldName;
+}
+
+@lombok.experimental.Accessors(chain = true, fluent = true)
+class GetterSetterJavadoc5 {
+	/**
+	 * Some text
+	 *
+	 * **SETTER**
+	 * Setter section
+	 * @param fieldName Hello, World5
+	 * @return Sky is blue5
+	 * **GETTER**
+	 * Getter section
+	 * @return Sky is blue5
+	 */
+	@lombok.Getter @lombok.Setter private int fieldName;
+}