diff --git a/gapic-generator-java/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java b/gapic-generator-java/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java index 12300b862c..1f2b980f3f 100644 --- a/gapic-generator-java/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java +++ b/gapic-generator-java/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java @@ -51,6 +51,7 @@ public abstract static class Builder { String throwsType = null; String throwsDescription = null; String deprecated = null; + String returnDescription = null; List paramsList = new ArrayList<>(); List componentsList = new ArrayList<>(); // Private accessor, set complete and consolidated comment. @@ -69,6 +70,11 @@ public Builder setDeprecated(String deprecatedText) { return this; } + public Builder setReturn(String returnText) { + returnDescription = returnText; + return this; + } + public Builder addParam(String name, String description) { paramsList.add(String.format("@param %s %s", name, processParamComment(description))); return this; @@ -129,12 +135,13 @@ public boolean emptyComments() { return Strings.isNullOrEmpty(throwsType) && Strings.isNullOrEmpty(throwsDescription) && Strings.isNullOrEmpty(deprecated) + && Strings.isNullOrEmpty(returnDescription) && paramsList.isEmpty() && componentsList.isEmpty(); } public JavaDocComment build() { - // @param, @throws and @deprecated should always get printed at the end. + // @param, @throws, @return, and @deprecated should always get printed at the end. componentsList.addAll(paramsList); if (!Strings.isNullOrEmpty(throwsType)) { componentsList.add( @@ -143,6 +150,9 @@ public JavaDocComment build() { if (!Strings.isNullOrEmpty(deprecated)) { componentsList.add(String.format("@deprecated %s", deprecated)); } + if (!Strings.isNullOrEmpty(returnDescription)) { + componentsList.add(String.format("@return %s", returnDescription)); + } // Escape component in list one by one, because we will join the components by `\n` // `\n` will be taken as escape character by the comment escaper. componentsList = diff --git a/gapic-generator-java/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java b/gapic-generator-java/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java index 0d3550971d..ebc0bfa43b 100644 --- a/gapic-generator-java/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java +++ b/gapic-generator-java/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java @@ -22,6 +22,16 @@ import org.junit.Test; public class JavaDocCommentTest { + @Test + public void emptyJavaDocComment() { + JavaDocComment.Builder javaDocCommentBuilder = JavaDocComment.builder(); + assertEquals(true, javaDocCommentBuilder.emptyComments()); + + String content = "testing return"; + javaDocCommentBuilder.setReturn(content); + assertEquals(false, javaDocCommentBuilder.emptyComments()); + } + @Test public void createJavaDocComment_basic() { String content = "this is a test comment"; @@ -153,9 +163,34 @@ public void createJavaDocComment_multipleParams() { } @Test - public void createJavaDocComment_throwsAndDeprecated() { - // No matter how many times or order `setThrows` and `setDeprecated` are called, - // only one @throws and @deprecated will be printed. + public void createJavaDocComment_multipleParamsAndReturn() { + // Parameters should be grouped together and get printed after block comments. + // Return text should get printed at the very end. + String comment = "This is a block comment."; + String paramName1 = "shelfName"; + String paramDescription1 = "The name of the shelf where books are published to."; + String paramName2 = "shelfId"; + String paramDescription2 = "The shelfId of the shelf where books are published to."; + String returnText = "This is the method return text."; + JavaDocComment javaDocComment = + JavaDocComment.builder() + .addParam(paramName1, paramDescription1) + .addParam(paramName2, paramDescription2) + .addComment(comment) + .setReturn(returnText) + .build(); + String expected = + "This is a block comment.\n" + + "@param shelfName The name of the shelf where books are published to.\n" + + "@param shelfId The shelfId of the shelf where books are published to.\n" + + "@return This is the method return text."; + assertEquals(expected, javaDocComment.comment()); + } + + @Test + public void createJavaDocComment_throwsAndDeprecatedAndReturn() { + // No matter how many times or order `setThrows`, `setDeprecated`, `setReturn` are called, + // only one @throws, @deprecated, and @return will be printed. String throwsType = "com.google.api.gax.rpc.ApiException"; String throwsDescription = "if the remote call fails."; String throwsType_print = "java.lang.RuntimeException"; @@ -164,28 +199,35 @@ public void createJavaDocComment_throwsAndDeprecated() { String deprecatedText = "Use the {@link ArchivedBookName} class instead."; String deprecatedText_print = "Use the {@link ShelfBookName} class instead."; + String returnText = "This is the incorrect method return text."; + String returnText_print = "This is the correct method return text."; + JavaDocComment javaDocComment = JavaDocComment.builder() .setThrows(throwsType, throwsDescription) .setDeprecated(deprecatedText) + .setReturn(returnText) .setThrows(throwsType_print, throwsDescription_print) .setDeprecated(deprecatedText_print) + .setReturn(returnText_print) .build(); String expected = LineFormatter.lines( "@throws java.lang.RuntimeException if the remote call fails.\n", - "@deprecated Use the {@link ShelfBookName} class instead."); + "@deprecated Use the {@link ShelfBookName} class instead.\n", + "@return This is the correct method return text."); assertEquals(expected, javaDocComment.comment()); } @Test public void createJavaDocComment_allComponents() { - // No matter what order `setThrows`, `setDeprecated` are called, + // No matter what order `setThrows`, `setDeprecated`, and `setReturn` are called, // They will be printed at the end. And `@param` should be grouped, - // they should always be printed right before `@throws` and `@deprecated`. + // they should always be printed right before `@throws`, `@deprecated`, and `@return`. // All other add methods should keep the order of how they are added. String content = "this is a test comment"; String deprecatedText = "Use the {@link ArchivedBookName} class instead."; + String returnText = "This is the method return text."; String paramName1 = "shelfName"; String paramDescription1 = "The name of the shelf where books are published to."; String paramName2 = "shelf"; @@ -204,6 +246,7 @@ public void createJavaDocComment_allComponents() { JavaDocComment.builder() .setDeprecated(deprecatedText) .setThrows(throwsType, throwsDescription) + .setReturn(returnText) .addParam(paramName1, paramDescription1) .addComment(content) .addParagraph(paragraph1) @@ -226,7 +269,8 @@ public void createJavaDocComment_allComponents() { "@param shelfName The name of the shelf where books are published to.\n", "@param shelf The shelf to create.\n", "@throws com.google.api.gax.rpc.ApiException if the remote call fails.\n", - "@deprecated Use the {@link ArchivedBookName} class instead."); + "@deprecated Use the {@link ArchivedBookName} class instead.\n", + "@return This is the method return text."); assertEquals(expected, javaDocComment.comment()); } }