From ea7a02ee88f8a3aa9afd3a9268390f4f9fee4b59 Mon Sep 17 00:00:00 2001 From: Shaishav Gandhi Date: Wed, 3 Oct 2018 19:59:30 -0700 Subject: Add Javadoc to ParameterSpec (#676) * Add Javadoc to ParameterSpec Signed-off-by: shaishavgandhi05 * Move emission to same CodeBlock Signed-off-by: shaishavgandhi05 * Remove eager javadoc addition and fallback to adding doc when emitting Signed-off-by: shaishavgandhi05 * Fix formatting Signed-off-by: shaishavgandhi05 * Add new line before emitting parameter javadoc Signed-off-by: shaishavgandhi05 * Emit new line before @param only if method javadoc is present Signed-off-by: shaishavgandhi05 --- .../java/com/squareup/javapoet/MethodSpec.java | 16 ++++++- .../java/com/squareup/javapoet/ParameterSpec.java | 13 ++++++ .../java/com/squareup/javapoet/MethodSpecTest.java | 53 ++++++++++++++++++++++ 3 files changed, 81 insertions(+), 1 deletion(-) 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 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 annotations; public final Set 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 annotations = new ArrayList<>(); private final List 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 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); -- cgit v1.2.3