Add Javadoc to ParameterSpec (#676)

* Add Javadoc to ParameterSpec

Signed-off-by: shaishavgandhi05 <shaishgandhi@gmail.com>

* Move emission to same CodeBlock

Signed-off-by: shaishavgandhi05 <shaishgandhi@gmail.com>

* Remove eager javadoc addition and fallback to adding doc when emitting

Signed-off-by: shaishavgandhi05 <shaishgandhi@gmail.com>

* Fix formatting

Signed-off-by: shaishavgandhi05 <shaishgandhi@gmail.com>

* Add new line before emitting parameter javadoc

Signed-off-by: shaishavgandhi05 <shaishgandhi@gmail.com>

* Emit new line before @param only if method javadoc is present

Signed-off-by: shaishavgandhi05 <shaishgandhi@gmail.com>

3 files changed, 81 insertions, 1 deletions

diff --git a/src/main/java/com/squareup/javapoet/MethodSpec.java b/src/main/java/com/squareup/javapoet/MethodSpec.java
index 52b41e7..0bfdd1b 100644
--- a/src/main/java/com/squareup/javapoet/MethodSpec.java
+++ b/src/main/java/com/squareup/javapoet/MethodSpec.java
@@ -82,7 +82,7 @@ public final class MethodSpec {
 
   void emit(CodeWriter codeWriter, String enclosingName, Set<Modifier> implicitModifiers)
       throws IOException {
-    codeWriter.emitJavadoc(javadoc);
+    codeWriter.emitJavadoc(javadocWithParameters());
     codeWriter.emitAnnotations(annotations, false);
     codeWriter.emitModifiers(modifiers, implicitModifiers);
 
@@ -140,6 +140,20 @@ public final class MethodSpec {
     codeWriter.popTypeVariables(typeVariables);
   }
 
+  private CodeBlock javadocWithParameters() {
+    CodeBlock.Builder builder = javadoc.toBuilder();
+    boolean emitTagNewline = true;
+    for (ParameterSpec parameterSpec : parameters) {
+      if (!parameterSpec.javadoc.isEmpty()) {
+        // Emit a new line before @param section only if the method javadoc is present.
+        if (emitTagNewline && !javadoc.isEmpty()) builder.add("\n");
+        emitTagNewline = false;
+        builder.add("@param $L $L", parameterSpec.name, parameterSpec.javadoc);
+      }
+    }
+    return builder.build();
+  }
+
   public boolean hasModifier(Modifier modifier) {
     return modifiers.contains(modifier);
   }
diff --git a/src/main/java/com/squareup/javapoet/ParameterSpec.java b/src/main/java/com/squareup/javapoet/ParameterSpec.java
index e30cb0f..e98b99e 100644
--- a/src/main/java/com/squareup/javapoet/ParameterSpec.java
+++ b/src/main/java/com/squareup/javapoet/ParameterSpec.java
@@ -35,12 +35,14 @@ public final class ParameterSpec {
   public final List<AnnotationSpec> annotations;
   public final Set<Modifier> modifiers;
   public final TypeName type;
+  public final CodeBlock javadoc;
 
   private ParameterSpec(Builder builder) {
     this.name = checkNotNull(builder.name, "name == null");
     this.annotations = Util.immutableList(builder.annotations);
     this.modifiers = Util.immutableSet(builder.modifiers);
     this.type = checkNotNull(builder.type, "type == null");
+    this.javadoc = builder.javadoc.build();
   }
 
   public boolean hasModifier(Modifier modifier) {
@@ -121,6 +123,7 @@ public final class ParameterSpec {
   public static final class Builder {
     private final TypeName type;
     private final String name;
+    private final CodeBlock.Builder javadoc = CodeBlock.builder();
 
     private final List<AnnotationSpec> annotations = new ArrayList<>();
     private final List<Modifier> modifiers = new ArrayList<>();
@@ -130,6 +133,16 @@ public final class ParameterSpec {
       this.name = name;
     }
 
+    public Builder addJavadoc(String format, Object... args) {
+      javadoc.add(format, args);
+      return this;
+    }
+
+    public Builder addJavadoc(CodeBlock block) {
+      javadoc.add(block);
+      return this;
+    }
+
     public Builder addAnnotations(Iterable<AnnotationSpec> annotationSpecs) {
       checkArgument(annotationSpecs != null, "annotationSpecs == null");
       for (AnnotationSpec annotationSpec : annotationSpecs) {
diff --git a/src/test/java/com/squareup/javapoet/MethodSpecTest.java b/src/test/java/com/squareup/javapoet/MethodSpecTest.java
index 5dfabaa..c6e05c6 100644
--- a/src/test/java/com/squareup/javapoet/MethodSpecTest.java
+++ b/src/test/java/com/squareup/javapoet/MethodSpecTest.java
@@ -270,6 +270,59 @@ public final class MethodSpecTest {
     assertThat(a.hashCode()).isEqualTo(b.hashCode());
   }
 
+  @Test public void withoutParameterJavaDoc() {
+    MethodSpec methodSpec = MethodSpec.methodBuilder("getTaco")
+        .addModifiers(Modifier.PRIVATE)
+        .addParameter(TypeName.DOUBLE, "money")
+        .addJavadoc("Gets the best Taco\n")
+        .build();
+    assertThat(methodSpec.toString()).isEqualTo(""
+        + "/**\n"
+        + " * Gets the best Taco\n"
+        + " */\n"
+        + "private void getTaco(double money) {\n"
+        + "}\n");
+  }
+
+  @Test public void withParameterJavaDoc() {
+    MethodSpec methodSpec = MethodSpec.methodBuilder("getTaco")
+        .addParameter(ParameterSpec.builder(TypeName.DOUBLE, "money")
+            .addJavadoc("the amount required to buy the taco.\n")
+            .build())
+        .addParameter(ParameterSpec.builder(TypeName.INT, "count")
+            .addJavadoc("the number of Tacos to buy.\n")
+            .build())
+        .addJavadoc("Gets the best Taco money can buy.\n")
+        .build();
+    assertThat(methodSpec.toString()).isEqualTo(""
+        + "/**\n"
+        + " * Gets the best Taco money can buy.\n"
+        + " *\n"
+        + " * @param money the amount required to buy the taco.\n"
+        + " * @param count the number of Tacos to buy.\n"
+        + " */\n"
+        + "void getTaco(double money, int count) {\n"
+        + "}\n");
+  }
+
+  @Test public void withParameterJavaDocAndWithoutMethodJavadoc() {
+    MethodSpec methodSpec = MethodSpec.methodBuilder("getTaco")
+        .addParameter(ParameterSpec.builder(TypeName.DOUBLE, "money")
+            .addJavadoc("the amount required to buy the taco.\n")
+            .build())
+        .addParameter(ParameterSpec.builder(TypeName.INT, "count")
+            .addJavadoc("the number of Tacos to buy.\n")
+            .build())
+        .build();
+    assertThat(methodSpec.toString()).isEqualTo(""
+        + "/**\n"
+        + " * @param money the amount required to buy the taco.\n"
+        + " * @param count the number of Tacos to buy.\n"
+        + " */\n"
+        + "void getTaco(double money, int count) {\n"
+        + "}\n");
+  }
+
   @Test public void duplicateExceptionsIgnored() {
     ClassName ioException = ClassName.get(IOException.class);
     ClassName timeoutException = ClassName.get(TimeoutException.class);