[fixes projectlombok#933] Add javadoc for generated constructors

src/core/lombok/core/handlers/HandlerUtil.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2013-2022 The Project Lombok Authors.
+ * Copyright (C) 2013-2024 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
@@ -981,4 +981,20 @@ public static String getParamJavadoc(String methodComment, String param) {
  }
  return null;
  }
+
+ public static String getConstructorJavadocHeader(String typeName) {
+ return "Creates a new {@code " + typeName + "} instance.\n\n";
+ }
+
+ public static String getConstructorParameterJavadoc(String paramName, String fieldJavadoc) {
+ String fieldBaseJavadoc = stripSectionsFromJavadoc(fieldJavadoc);
+
+ String paramJavadoc = getParamJavadoc(fieldBaseJavadoc, paramName);
+ if (paramJavadoc == null) {
+ paramJavadoc = stripLinesWithTagFromJavadoc(fieldBaseJavadoc, JavadocTag.PARAM);
+ paramJavadoc = stripLinesWithTagFromJavadoc(paramJavadoc, JavadocTag.RETURN);
+ }
+
+ return paramJavadoc;
+ }
 }

src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java

@@ -2815,10 +2815,14 @@ public static String getDocComment(EclipseNode eclipseNode) {
  return null;
  }
 
+ public static void setDocComment(EclipseNode typeNode, EclipseNode eclipseNode, String doc) {
+ setDocComment((CompilationUnitDeclaration) eclipseNode.top().get(), (TypeDeclaration) typeNode.get(), eclipseNode.get(), doc);
+ }
+
  public static void setDocComment(CompilationUnitDeclaration cud, EclipseNode eclipseNode, String doc) {
  setDocComment(cud, (TypeDeclaration) upToTypeNode(eclipseNode).get(), eclipseNode.get(), doc);
  }
-  
+
  public static void setDocComment(CompilationUnitDeclaration cud, TypeDeclaration type, ASTNode node, String doc) {
  if (doc == null) return;
 

src/core/lombok/eclipse/handlers/HandleConstructor.java

@@ -22,7 +22,7 @@
 package lombok.eclipse.handlers;
 
 import static lombok.core.handlers.HandlerUtil.*;
-import static lombok.eclipse.Eclipse.*;
+import static lombok.eclipse.Eclipse.ECLIPSE_DO_NOT_TOUCH_FLAG;
 import static lombok.eclipse.handlers.EclipseHandlerUtil.*;
 
 import java.lang.reflect.Modifier;
@@ -286,15 +286,17 @@ public void generate(
  ConstructorDeclaration constr = createConstructor(
  staticConstrRequired ? AccessLevel.PRIVATE : level, typeNode, fieldsToParam, forceDefaults,
  sourceNode, onConstructor);
- injectMethod(typeNode, constr);
+ EclipseNode constructorNode = injectMethod(typeNode, constr);
+ generateConstructorJavadoc(typeNode, constructorNode, fieldsToParam);
  }
  generateStaticConstructor(staticConstrRequired, typeNode, staticName, level, fieldsToParam, source);
  }
 
  private void generateStaticConstructor(boolean staticConstrRequired, EclipseNode typeNode, String staticName, AccessLevel level, Collection<EclipseNode> fields, ASTNode source) {
  if (staticConstrRequired) {
  MethodDeclaration staticConstr = createStaticConstructor(level, staticName, typeNode, fields, source);
- injectMethod(typeNode, staticConstr);
+ EclipseNode constructorNode = injectMethod(typeNode, staticConstr);
+ generateConstructorJavadoc(typeNode, constructorNode, fields);
  }
  }
 
@@ -584,4 +586,27 @@ public MethodDeclaration createStaticConstructor(AccessLevel level, String name,
  constructor.traverse(new SetGeneratedByVisitor(source), typeDecl.scope);
  return constructor;
  }
+
+ private void generateConstructorJavadoc(EclipseNode typeNode, EclipseNode constructorNode, Collection<EclipseNode> fields) {
+ if (fields.isEmpty()) return;
+
+ String constructorJavadoc = getConstructorJavadocHeader(typeNode.getName());
+ boolean fieldDescriptionAdded = false;
+ for (EclipseNode fieldNode : fields) {
+ String paramName = String.valueOf(removePrefixFromField(fieldNode));
+ String fieldJavadoc = getDocComment(fieldNode);
+ String paramJavadoc = getConstructorParameterJavadoc(paramName, fieldJavadoc);
+
+ if (paramJavadoc == null) {
+ paramJavadoc = "";
+ } else {
+ fieldDescriptionAdded = true;
+ }
+
+ constructorJavadoc = addJavadocLine(constructorJavadoc, "@param " + paramName + " " + paramJavadoc);
+ }
+ if (fieldDescriptionAdded) {
+ setDocComment(typeNode, constructorNode, constructorJavadoc);
+ }
+ }
 }

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

@@ -30,6 +30,7 @@
 import com.sun.tools.javac.tree.JCTree.JCAnnotation;
 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.JCMethodDecl;
@@ -251,6 +252,7 @@ private void generate(JavacNode typeNode, AccessLevel level, List<JCAnnotation>
 
  if (!(skipIfConstructorExists != SkipIfConstructorExists.NO && constructorExists(typeNode) != MemberExistsResult.NOT_EXISTS)) {
  JCMethodDecl constr = createConstructor(staticConstrRequired ? AccessLevel.PRIVATE : level, onConstructor, typeNode, fields, allToDefault, source);
+ generateConstructorJavadoc(constr, typeNode, fields);
  injectMethod(typeNode, constr);
  }
  generateStaticConstructor(staticConstrRequired, typeNode, staticName, level, allToDefault, fields, source);
@@ -259,6 +261,7 @@ private void generate(JavacNode typeNode, AccessLevel level, List<JCAnnotation>
  private void generateStaticConstructor(boolean staticConstrRequired, JavacNode typeNode, String staticName, AccessLevel level, boolean allToDefault, List<JavacNode> fields, JavacNode source) {
  if (staticConstrRequired) {
  JCMethodDecl staticConstr = createStaticConstructor(staticName, level, typeNode, allToDefault ? List.<JavacNode>nil() : fields, source);
+ generateConstructorJavadoc(staticConstr, typeNode, fields);
  injectMethod(typeNode, staticConstr);
  }
  }
@@ -474,4 +477,28 @@ public JCMethodDecl createStaticConstructor(String name, AccessLevel level, Java
  createRelevantNonNullAnnotation(typeNode, methodDef);
  return recursiveSetGeneratedBy(methodDef, source);
  }
+
+ private void generateConstructorJavadoc(JCMethodDecl constructor, JavacNode typeNode, List<JavacNode> fields) {
+ if (fields.isEmpty()) return;
+
+ JCCompilationUnit cu = ((JCCompilationUnit) typeNode.top().get());
+ String constructorJavadoc = getConstructorJavadocHeader(typeNode.getName());
+ boolean fieldDescriptionAdded = false;
+ for (JavacNode fieldNode : fields) {
+ String paramName = removePrefixFromField(fieldNode).toString();
+ String fieldJavadoc = getDocComment(cu, fieldNode.get());
+ String paramJavadoc = getConstructorParameterJavadoc(paramName, fieldJavadoc);
+
+ if (paramJavadoc == null) {
+ paramJavadoc = "";
+ } else {
+ fieldDescriptionAdded = true;
+ }
+
+ constructorJavadoc = addJavadocLine(constructorJavadoc, "@param " + paramName + " " + paramJavadoc);
+ }
+ if (fieldDescriptionAdded) {
+ setDocComment(cu, constructor, constructorJavadoc);
+ }
+ }
 }

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

@@ -87,6 +87,15 @@ public java.lang.String toString() {
  return "BuilderJavadoc.BuilderJavadocBuilder(basic=" + this.basic + ", getsetwith=" + this.getsetwith + ", predef=" + this.predef + ", predefWithJavadoc=" + this.predefWithJavadoc + ")";
  }
  }
+ /**
+ * Creates a new {@code BuilderJavadoc} instance.
+ *
+ * @param basic basic gets only a builder setter.
+ * @see #getsetwith
+ * @param getsetwith getsetwith gets a builder setter, an instance getter and setter, and a wither.
+ * @param predef Predef has a predefined builder setter with no javadoc, and the builder setter does not get this one.
+ * @param predefWithJavadoc predefWithJavadoc has a predefined builder setter with javadoc, so it keeps that one untouched.
+ */
  @java.lang.SuppressWarnings("all")
  @lombok.Generated
  BuilderJavadoc(final int basic, final int getsetwith, final int predef, final int predefWithJavadoc) {

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

@@ -10,6 +10,14 @@ public class BuilderWithDeprecated {
  java.util.List<String> strings;
  @Deprecated
  ImmutableList<Integer> numbers;
+ /**
+ * Creates a new {@code BuilderWithDeprecated} instance.
+ *
+ * @param dep1 @deprecated since always
+ * @param dep2 
+ * @param strings 
+ * @param numbers 
+ */
  @java.lang.SuppressWarnings("all")
  @lombok.Generated
  BuilderWithDeprecated(final String dep1, final int dep2, final java.util.List<String> strings, final ImmutableList<Integer> numbers) {

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

@@ -0,0 +1,28 @@
+public class ConstructorJavadoc {
+ /**
+ * Some text
+ *
+ * @param fieldName Hello, World1
+ * --- GETTER ---
+ * Getter section
+ *
+ * @return Sky is blue1
+ */
+ private int fieldName;
+ /**
+ * Sky is blue
+ */
+ private int fieldName2;
+ /**
+ * Creates a new {@code ConstructorJavadoc} instance.
+ *
+ * @param fieldName Some text
+ * @param fieldName2 Sky is blue
+ */
+ @java.lang.SuppressWarnings("all")
+ @lombok.Generated
+ public ConstructorJavadoc(final int fieldName, final int fieldName2) {
+ this.fieldName = fieldName;
+ this.fieldName2 = fieldName2;
+ }
+}

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

@@ -46,6 +46,15 @@ public BuilderJavadocBuilder<T> predefWithJavadoc(final int x) {
  private @lombok.Getter @lombok.Setter @lombok.experimental.Wither int getsetwith;
  private final int predef;
  private final int predefWithJavadoc;
+ /**
+ * Creates a new {@code BuilderJavadoc} instance.
+ * 
+ * @param basic basic gets only a builder setter.
+ * @see #getsetwith
+ * @param getsetwith getsetwith gets a builder setter, an instance getter and setter, and a wither.
+ * @param predef Predef has a predefined builder setter with no javadoc, and the builder setter does not get this one.
+ * @param predefWithJavadoc predefWithJavadoc has a predefined builder setter with javadoc, so it keeps that one untouched.
+ */
  @java.lang.SuppressWarnings("all") @lombok.Generated BuilderJavadoc(final int basic, final int getsetwith, final int predef, final int predefWithJavadoc) {
  super();
  this.basic = basic;

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

@@ -89,6 +89,14 @@
  @Deprecated int dep2;
  @Singular @Deprecated java.util.List<String> strings;
  @Singular @Deprecated ImmutableList<Integer> numbers;
+ /**
+ * Creates a new {@code BuilderWithDeprecated} instance.
+ *
+ * @param dep1 @deprecated since always
+ * @param dep2 
+ * @param strings 
+ * @param numbers 
+ */
  @java.lang.SuppressWarnings("all") @lombok.Generated BuilderWithDeprecated(final String dep1, final int dep2, final java.util.List<String> strings, final ImmutableList<Integer> numbers) {
  super();
  this.dep1 = dep1;

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

@@ -0,0 +1,16 @@
+import lombok.AllArgsConstructor;
+public @AllArgsConstructor class ConstructorJavadoc {
+ private int fieldName;
+ private int fieldName2;
+ /**
+ * Creates a new {@code ConstructorJavadoc} instance.
+ * 
+ * @param fieldName Some text
+ * @param fieldName2 Sky is blue
+ */
+ public @java.lang.SuppressWarnings("all") @lombok.Generated ConstructorJavadoc(final int fieldName, final int fieldName2) {
+ super();
+ this.fieldName = fieldName;
+ this.fieldName2 = fieldName2;
+ }
+}

test/transform/resource/before/ConstructorJavadoc.java

@@ -0,0 +1,20 @@
+import lombok.AllArgsConstructor;
+
+@AllArgsConstructor
+public class ConstructorJavadoc {
+ /**
+ * Some text
+ *
+ * @param fieldName Hello, World1
+ * --- GETTER ---
+ * Getter section
+ *
+ * @return Sky is blue1
+ */
+ private int fieldName;
+
+ /**
+ * Sky is blue
+ */
+ private int fieldName2;
+}