Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alicejli merged 1 commit into from
Jan 18, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 14 additions & 4 deletions ...in/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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))
Copy link
Contributor

@blakeli0 blakeli0 Jan 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's see if we can refactor CommentFormatter so that it can be used for the whole table, otherwise this issue may happen again in the future. That being said, if it turns out to be more complicated that it supposed to, we can merge this for now and create another issue to track the refactoring effort.

Copy link
Contributor Author

@alicejli alicejli Jan 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I investigated this a bit and I think it would be a little tricky to refactor CommentFormatter to be able to be applied to a whole table as I think it would need to have changes (or additions) to JavadocComment to only escape certain characters if they're not part of an html tag.

I could rewrite the table in general to use JavadocComment instead of StringBuilder so at least it would be explicitly clear when we are not applying standard formatting (e.g. escaping HTML characters). Let me know if you think that's worth doing or if I should create an issue for the larger refactoring effort.

Copy link
Contributor Author

@alicejli alicejli Jan 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tracking issue for refactor: #2385

.append("</td>\n")
.append(" <td>")
.append(CommentFormatter.formatAsJavaDocComment(method.description, null))
Expand All @@ -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");
Expand Down
9 changes: 5 additions & 4 deletions .../google/api/generator/engine/writer/goldens/GrpcServiceClientWithNestedClassImport.golden
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
13 changes: 7 additions & 6 deletions .../src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/BookshopClient.golden
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
15 changes: 8 additions & 7 deletions .../java/com/google/api/generator/gapic/composer/grpc/goldens/DeprecatedServiceClient.golden
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
83 changes: 42 additions & 41 deletions ...java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoClient.golden
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading