fix: format method types and table in Client Overview (#2361)

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

@@ -31,6 +31,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.stream.Collectors;
 
 public class ServiceClientCommentComposer {
   // Tokens.
@@ -231,15 +232,17 @@ private static String createTableOfMethods(List<MethodAndVariants> methodAndVari
     StringBuilder tableBuilder = new StringBuilder();
     tableBuilder
         .append("<table>\n")
+        .append("   <caption>Methods</caption>\n")
         .append("   <tr>\n")
         .append("     <th>Method</th>\n")
         .append("     <th>Description</th>\n")
-        .append("     <th>Method Variants</th>\n");
+        .append("     <th>Method Variants</th>\n")
+        .append("   </tr>\n");
     for (MethodAndVariants method : methodAndVariantsList) {
       tableBuilder
           .append("   <tr>\n")
           .append("     <td>")
-          .append(method.method)
+          .append(CommentFormatter.formatAsJavaDocComment(method.method, null))
           .append("</td>\n")
           .append("     <td>")
           .append(CommentFormatter.formatAsJavaDocComment(method.description, null))
@@ -253,18 +256,25 @@ private static String createTableOfMethods(List<MethodAndVariants> methodAndVari
       generateUnorderedListMethodVariants(tableBuilder, CALLABLE_METHODS, method.callableVariants);
       tableBuilder.append("      </td>\n").append("   </tr>\n");
     }
-    tableBuilder.append("   </tr>\n").append(" </table>\n");
+    tableBuilder.append(" </table>\n");
     return tableBuilder.toString();
   }
 
   private static void generateUnorderedListMethodVariants(
       StringBuilder tableBuilder, String methodType, List<String> methodVariants) {
+    List<String> formattedMethodVariants =
+        methodVariants.stream()
+            .map(
+                methodVariant ->
+                    CommentFormatter.formatAsJavaDocComment(
+                        methodVariant, null)) // Apply the formatting to each element
+            .collect(Collectors.toList());
     if (!methodVariants.isEmpty()) {
       tableBuilder
           .append("     " + methodType + "     ")
           .append("<ul>\n")
           .append("          <li>")
-          .append(String.join("\n          <li>", methodVariants))
+          .append(String.join("\n          <li>", formattedMethodVariants))
           .append("\n")
           .append("     </ul>")
           .append("\n");

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

@@ -32,25 +32,26 @@ import javax.annotation.Generated;
  * calls close().
  *
  * <table>
+ *    <caption>Methods</caption>
  *    <tr>
  *      <th>Method</th>
  *      <th>Description</th>
  *      <th>Method Variants</th>
+ *    </tr>
  *    <tr>
- *      <td>NestedMessageMethod</td>
+ *      <td><p> NestedMessageMethod</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>
- *           <li>nestedMessageMethod(Outer.Middle request)
+ *           <li><p> nestedMessageMethod(Outer.Middle request)
  *      </ul>
  *      <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>
- *           <li>nestedMessageMethodCallable()
+ *           <li><p> nestedMessageMethodCallable()
  *      </ul>
  *       </td>
  *    </tr>
- *    </tr>
  *  </table>
  *
  * <p>See the individual methods for example code.

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

@@ -32,30 +32,31 @@ import javax.annotation.Generated;
  * threads. In the example above, try-with-resources is used, which automatically calls close().
  *
  * <table>
+ *    <caption>Methods</caption>
  *    <tr>
  *      <th>Method</th>
  *      <th>Description</th>
  *      <th>Method Variants</th>
+ *    </tr>
  *    <tr>
- *      <td>GetBook</td>
+ *      <td><p> GetBook</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>
- *           <li>getBook(GetBookRequest request)
+ *           <li><p> getBook(GetBookRequest request)
  *      </ul>
  *      <p>"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.</p>
  *      <ul>
- *           <li>getBook(int booksCount, List<Book> books)
- *           <li>getBook(String booksList, List<Book> books)
+ *           <li><p> getBook(int booksCount, List&lt;Book&gt; books)
+ *           <li><p> getBook(String booksList, List&lt;Book&gt; books)
  *      </ul>
  *      <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>
- *           <li>getBookCallable()
+ *           <li><p> getBookCallable()
  *      </ul>
  *       </td>
  *    </tr>
- *    </tr>
  *  </table>
  *
  * <p>See the individual methods for example code.

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

@@ -31,39 +31,40 @@ import javax.annotation.Generated;
  * close().
  *
  * <table>
+ *    <caption>Methods</caption>
  *    <tr>
  *      <th>Method</th>
  *      <th>Description</th>
  *      <th>Method Variants</th>
+ *    </tr>
  *    <tr>
- *      <td>FastFibonacci</td>
+ *      <td><p> FastFibonacci</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>
- *           <li>fastFibonacci(FibonacciRequest request)
+ *           <li><p> fastFibonacci(FibonacciRequest request)
  *      </ul>
  *      <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>
- *           <li>fastFibonacciCallable()
+ *           <li><p> fastFibonacciCallable()
  *      </ul>
  *       </td>
  *    </tr>
  *    <tr>
- *      <td>SlowFibonacci</td>
+ *      <td><p> SlowFibonacci</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>
- *           <li>slowFibonacci(FibonacciRequest request)
+ *           <li><p> slowFibonacci(FibonacciRequest request)
  *      </ul>
  *      <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>
- *           <li>slowFibonacciCallable()
+ *           <li><p> slowFibonacciCallable()
  *      </ul>
  *       </td>
  *    </tr>
- *    </tr>
  *  </table>
  *
  * <p>See the individual methods for example code.

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

@@ -53,158 +53,159 @@ import javax.annotation.Generated;
  * threads. In the example above, try-with-resources is used, which automatically calls close().
  *
  * <table>
+ *    <caption>Methods</caption>
  *    <tr>
  *      <th>Method</th>
  *      <th>Description</th>
  *      <th>Method Variants</th>
+ *    </tr>
  *    <tr>
- *      <td>Echo</td>
+ *      <td><p> Echo</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>
- *           <li>echo(EchoRequest request)
+ *           <li><p> echo(EchoRequest request)
  *      </ul>
  *      <p>"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.</p>
  *      <ul>
- *           <li>echo()
- *           <li>echo(ResourceName parent)
- *           <li>echo(Status error)
- *           <li>echo(FoobarName name)
- *           <li>echo(String content)
- *           <li>echo(String name)
- *           <li>echo(String parent)
- *           <li>echo(String content, Severity severity)
+ *           <li><p> echo()
+ *           <li><p> echo(ResourceName parent)
+ *           <li><p> echo(Status error)
+ *           <li><p> echo(FoobarName name)
+ *           <li><p> echo(String content)
+ *           <li><p> echo(String name)
+ *           <li><p> echo(String parent)
+ *           <li><p> echo(String content, Severity severity)
  *      </ul>
  *      <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>
- *           <li>echoCallable()
+ *           <li><p> echoCallable()
  *      </ul>
  *       </td>
  *    </tr>
  *    <tr>
- *      <td>Expand</td>
+ *      <td><p> Expand</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>
- *           <li>expandCallable()
+ *           <li><p> expandCallable()
  *      </ul>
  *       </td>
  *    </tr>
  *    <tr>
- *      <td>Collect</td>
+ *      <td><p> Collect</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>
- *           <li>collectCallable()
+ *           <li><p> collectCallable()
  *      </ul>
  *       </td>
  *    </tr>
  *    <tr>
- *      <td>Chat</td>
+ *      <td><p> Chat</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>
- *           <li>chatCallable()
+ *           <li><p> chatCallable()
  *      </ul>
  *       </td>
  *    </tr>
  *    <tr>
- *      <td>ChatAgain</td>
+ *      <td><p> ChatAgain</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>
- *           <li>chatAgainCallable()
+ *           <li><p> chatAgainCallable()
  *      </ul>
  *       </td>
  *    </tr>
  *    <tr>
- *      <td>PagedExpand</td>
+ *      <td><p> PagedExpand</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>
- *           <li>pagedExpand(PagedExpandRequest request)
+ *           <li><p> pagedExpand(PagedExpandRequest request)
  *      </ul>
  *      <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>
- *           <li>pagedExpandPagedCallable()
- *           <li>pagedExpandCallable()
+ *           <li><p> pagedExpandPagedCallable()
+ *           <li><p> pagedExpandCallable()
  *      </ul>
  *       </td>
  *    </tr>
  *    <tr>
- *      <td>SimplePagedExpand</td>
+ *      <td><p> SimplePagedExpand</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>
- *           <li>simplePagedExpand(PagedExpandRequest request)
+ *           <li><p> simplePagedExpand(PagedExpandRequest request)
  *      </ul>
  *      <p>"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.</p>
  *      <ul>
- *           <li>simplePagedExpand()
+ *           <li><p> simplePagedExpand()
  *      </ul>
  *      <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>
- *           <li>simplePagedExpandPagedCallable()
- *           <li>simplePagedExpandCallable()
+ *           <li><p> simplePagedExpandPagedCallable()
+ *           <li><p> simplePagedExpandCallable()
  *      </ul>
  *       </td>
  *    </tr>
  *    <tr>
- *      <td>Wait</td>
+ *      <td><p> Wait</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>
- *           <li>waitAsync(WaitRequest request)
+ *           <li><p> waitAsync(WaitRequest request)
  *      </ul>
  *      <p>Methods that return long-running operations have "Async" method variants that return `OperationFuture`, which is used to track polling of the service.</p>
  *      <ul>
- *           <li>waitAsync(Duration ttl)
- *           <li>waitAsync(Timestamp endTime)
+ *           <li><p> waitAsync(Duration ttl)
+ *           <li><p> waitAsync(Timestamp endTime)
  *      </ul>
  *      <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>
- *           <li>waitOperationCallable()
- *           <li>waitCallable()
+ *           <li><p> waitOperationCallable()
+ *           <li><p> waitCallable()
  *      </ul>
  *       </td>
  *    </tr>
  *    <tr>
- *      <td>Block</td>
+ *      <td><p> Block</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>
- *           <li>block(BlockRequest request)
+ *           <li><p> block(BlockRequest request)
  *      </ul>
  *      <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>
- *           <li>blockCallable()
+ *           <li><p> blockCallable()
  *      </ul>
  *       </td>
  *    </tr>
  *    <tr>
- *      <td>CollideName</td>
+ *      <td><p> CollideName</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>
- *           <li>collideName(EchoRequest request)
+ *           <li><p> collideName(EchoRequest request)
  *      </ul>
  *      <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>
- *           <li>collideNameCallable()
+ *           <li><p> collideNameCallable()
  *      </ul>
  *       </td>
  *    </tr>
- *    </tr>
  *  </table>
  *
  * <p>See the individual methods for example code.