feat: update JavaDoc to use @return (#1233)

* feat: update JavaDoc to use @return

* add another test

* add unit test for emptyComments

* remove helper comment

Co-authored-by: Deepankar Dixit <[email protected]>

Author: alicejli

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<String> paramsList = new ArrayList<>();
     List<String> 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 =

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());
   }
 }