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>

2 files changed, 28 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) {