Skip to content

Commit

Permalink
fix: format proto comments in Client Overview (#2280)
Browse files Browse the repository at this point in the history 
* fix: format proto comments in Client Overview

* update showcase tests

* add failing unit test for JavaWriterVisitorTest
  • Loading branch information
@alicejli
alicejli committed Dec 11, 2023
1 parent 2cb0f9e commit 4029fbd
Show file tree
Hide file tree
Showing 34 changed files with 429 additions and 981 deletions.
2 changes: 1 addition & 1 deletion ...in/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
View file
Expand Up @@ -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(
Expand Down
20 changes: 20 additions & 0 deletions ...ator-java/src/test/java/com/google/api/generator/engine/writer/JavaWriterVisitorTest.java
View file
Expand Up @@ -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;
Expand Down Expand Up @@ -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 =
Expand Down
2 changes: 1 addition & 1 deletion .../google/api/generator/engine/writer/goldens/GrpcServiceClientWithNestedClassImport.golden
View file
Expand Up @@ -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>
Expand Down
2 changes: 1 addition & 1 deletion .../src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/BookshopClient.golden
View file
Expand Up @@ -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>
Expand Down
4 changes: 2 additions & 2 deletions .../java/com/google/api/generator/gapic/composer/grpc/goldens/DeprecatedServiceClient.golden
View file
Expand Up @@ -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>
Expand All @@ -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>
Expand Down
20 changes: 10 additions & 10 deletions ...java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/EchoClient.golden
View file
Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand Down
10 changes: 5 additions & 5 deletions .../src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/IdentityClient.golden
View file
Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand Down
28 changes: 14 additions & 14 deletions ...src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/MessagingClient.golden
View file
Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand Down

0 comments on commit 4029fbd

Please sign in to comment.