diff --git a/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java b/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java index 12300b862c..0e0b904e6d 100644 --- a/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java +++ b/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java @@ -52,6 +52,7 @@ public abstract static class Builder { String throwsDescription = null; String deprecated = null; List paramsList = new ArrayList<>(); + String returnText = null; List componentsList = new ArrayList<>(); // Private accessor, set complete and consolidated comment. abstract Builder setComment(String comment); @@ -69,6 +70,11 @@ public Builder setDeprecated(String deprecatedText) { return this; } + public Builder setReturn(String returnDescription) { + returnText = returnDescription; + return this; + } + public Builder addParam(String name, String description) { paramsList.add(String.format("@param %s %s", name, processParamComment(description))); return this; @@ -130,12 +136,16 @@ public boolean emptyComments() { && Strings.isNullOrEmpty(throwsDescription) && Strings.isNullOrEmpty(deprecated) && paramsList.isEmpty() + && Strings.isNullOrEmpty(returnText) && componentsList.isEmpty(); } public JavaDocComment build() { - // @param, @throws and @deprecated should always get printed at the end. + // @param, @return, @throws and @deprecated should always get printed at the end. componentsList.addAll(paramsList); + if (!Strings.isNullOrEmpty(returnText)) { + componentsList.add(String.format("@return %s", returnText)); + } if (!Strings.isNullOrEmpty(throwsType)) { componentsList.add( String.format("@throws %s %s", throwsType, HtmlEscaper.process(throwsDescription))); diff --git a/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java b/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java index 0d3550971d..1b531804b4 100644 --- a/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java +++ b/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java @@ -178,6 +178,30 @@ public void createJavaDocComment_throwsAndDeprecated() { assertEquals(expected, javaDocComment.comment()); } + @Test + public void createJavaDocComment_paramsAndReturn() { + // No matter how many times or order `setThrows` and `setDeprecated` are called, + // only one @throws and @deprecated will be printed. + String paramName1 = "shelfName"; + String paramDescription1 = "The name of the shelf where books are published to."; + String paramName2 = "shelf"; + String paramDescription2 = "The shelf to create."; + String returnText = "This is the method return text."; + + JavaDocComment javaDocComment = + JavaDocComment.builder() + .addParam(paramName1, paramDescription1) + .addParam(paramName2, paramDescription2) + .setReturn(returnText) + .build(); + String expected = + LineFormatter.lines( + "@param shelfName The name of the shelf where books are published to.\n", + "@param shelf The shelf to create.\n", + "@return This is the method return text."); + assertEquals(expected, javaDocComment.comment()); + } + @Test public void createJavaDocComment_allComponents() { // No matter what order `setThrows`, `setDeprecated` are called, @@ -190,6 +214,7 @@ public void createJavaDocComment_allComponents() { String paramDescription1 = "The name of the shelf where books are published to."; String paramName2 = "shelf"; String paramDescription2 = "The shelf to create."; + String returnText = "This is the method return text."; String paragraph1 = "This class provides the ability to make remote calls to the backing service through" + " method calls that map to API methods. Sample code to get started:"; @@ -210,6 +235,7 @@ public void createJavaDocComment_allComponents() { .addParagraph(paragraph2) .addOrderedList(orderedList) .addParam(paramName2, paramDescription2) + .setReturn(returnText) .build(); String expected = LineFormatter.lines( @@ -225,6 +251,7 @@ public void createJavaDocComment_allComponents() { "\n", "@param shelfName The name of the shelf where books are published to.\n", "@param shelf The shelf to create.\n", + "@return This is the method return text.\n", "@throws com.google.api.gax.rpc.ApiException if the remote call fails.\n", "@deprecated Use the {@link ArchivedBookName} class instead."); assertEquals(expected, javaDocComment.comment());