fix: format proto comments in Client Overview (#2280)

* fix: format proto comments in Client Overview

* update showcase tests

* add failing unit test for JavaWriterVisitorTest

Author: alicejli

gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java

@@ -242,7 +242,7 @@ private static String createTableOfMethods(List<MethodAndVariants> methodAndVari
           .append(method.method)
           .append("</td>\n")
           .append("     <td>")
-          .append("<p>" + method.description + "</p>")
+          .append(CommentFormatter.formatAsJavaDocComment(method.description, null))
           .append("</td>\n")
           .append("     <td>\n");
       generateUnorderedListMethodVariants(

gapic-generator-java/src/test/java/com/google/api/generator/engine/writer/JavaWriterVisitorTest.java

@@ -71,6 +71,7 @@
 import com.google.api.generator.engine.ast.Variable;
 import com.google.api.generator.engine.ast.VariableExpr;
 import com.google.api.generator.engine.ast.WhileStatement;
+import com.google.api.generator.engine.writer.JavaFormatter.FormatException;
 import com.google.api.generator.gapic.composer.grpc.ServiceClientClassComposer;
 import com.google.api.generator.gapic.model.GapicClass;
 import com.google.api.generator.gapic.model.GapicContext;
@@ -960,6 +961,25 @@ public void writeJavaDocComment_specialChar() {
     assertEquals(expected, writerVisitor.write());
   }
 
+  @Test
+  public void writeFailingComment_specialChar() {
+    JavaDocComment javaDocComment =
+        JavaDocComment.builder()
+            .addUnescapedComment(
+                "This resource reference needs to be CommentFormatted or it will fail: `bookShelves/*/`")
+            .build();
+
+    FormatException exceptionForIncorrectlyFormattedComment =
+        assertThrows(
+            FormatException.class,
+            () -> {
+              javaDocComment.accept(writerVisitor);
+            });
+    assertThat(exceptionForIncorrectlyFormattedComment)
+        .hasMessageThat()
+        .contains("The input resource can not be parsed");
+  }
+
   @Test
   public void writeTernaryExpr_basic() {
     Variable conditionVariable =

gapic-generator-java/src/test/java/com/google/api/generator/engine/writer/goldens/GrpcServiceClientWithNestedClassImport.golden

@@ -38,7 +38,7 @@ import javax.annotation.Generated;
  *      <th>Method Variants</th>
  *    <tr>
  *      <td>NestedMessageMethod</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/BookshopClient.golden

@@ -38,7 +38,7 @@ import javax.annotation.Generated;
  *      <th>Method Variants</th>
  *    <tr>
  *      <td>GetBook</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/DeprecatedServiceClient.golden

@@ -37,7 +37,7 @@ import javax.annotation.Generated;
  *      <th>Method Variants</th>
  *    <tr>
  *      <td>FastFibonacci</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -51,7 +51,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>SlowFibonacci</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoClient.golden

@@ -59,7 +59,7 @@ import javax.annotation.Generated;
  *      <th>Method Variants</th>
  *    <tr>
  *      <td>Echo</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -84,7 +84,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>Expand</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
  *      <ul>
@@ -94,7 +94,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>Collect</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
  *      <ul>
@@ -104,7 +104,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>Chat</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
  *      <ul>
@@ -114,7 +114,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>ChatAgain</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
  *      <ul>
@@ -124,7 +124,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>PagedExpand</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -139,7 +139,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>SimplePagedExpand</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -158,7 +158,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>Wait</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -178,7 +178,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>Block</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -192,7 +192,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>CollideName</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/IdentityClient.golden

@@ -47,7 +47,7 @@ import javax.annotation.Generated;
  *      <th>Method Variants</th>
  *    <tr>
  *      <td>CreateUser</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -67,7 +67,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>GetUser</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -86,7 +86,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>UpdateUser</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -100,7 +100,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>DeleteUser</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -119,7 +119,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>ListUsers</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/MessagingClient.golden

@@ -54,7 +54,7 @@ import javax.annotation.Generated;
  *      <th>Method Variants</th>
  *    <tr>
  *      <td>CreateRoom</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -72,7 +72,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>GetRoom</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -91,7 +91,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>UpdateRoom</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -105,7 +105,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>DeleteRoom</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -124,7 +124,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>ListRooms</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -139,7 +139,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>CreateBlurb</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -162,7 +162,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>GetBlurb</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -181,7 +181,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>UpdateBlurb</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -195,7 +195,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>DeleteBlurb</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -214,7 +214,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>ListBlurbs</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -235,7 +235,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>SearchBlurbs</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
  *      <ul>
@@ -254,7 +254,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>StreamBlurbs</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
  *      <ul>
@@ -264,7 +264,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>SendBlurbs</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
  *      <ul>
@@ -274,7 +274,7 @@ import javax.annotation.Generated;
  *    </tr>
  *    <tr>
  *      <td>Connect</td>
- *      <td><p></p></td>
+ *      <td><p> </td>
  *      <td>
  *      <p>Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.</p>
  *      <ul>