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

Author: alicejli

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.