fix(ast): update JavaDocComment to support @return.

googleapis · Jan 6, 2023 · 537e33c · 537e33c
1 parent 9b7336d
commit 537e33c
Show file tree

Hide file tree

Showing 2 changed files with 38 additions and 1 deletion.
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
@@ -52,6 +52,7 @@ public abstract static class Builder {
     String throwsDescription = null;
     String deprecated = null;
     List<String> paramsList = new ArrayList<>();
+    String returnText = null;
     List<String> 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
@@ -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() {
             "</ol>\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());