Skip to content

Commit 4029fbd

Browse files
alicejlialicejli
authored
fix: format proto comments in Client Overview (#2280)
* fix: format proto comments in Client Overview * update showcase tests * add failing unit test for JavaWriterVisitorTest
1 parent 2cb0f9e commit 4029fbd

File tree

34 files changed

+429
-981
lines changed

34 files changed

+429
-981
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -242,7 +242,7 @@ private static String createTableOfMethods(List<MethodAndVariants> methodAndVari
242242
.append(method.method)
243243
.append("</td>\n")
244244
.append(" <td>")
245-
.append("<p>" + method.description + "</p>")
245+
.append(CommentFormatter.formatAsJavaDocComment(method.description, null))
246246
.append("</td>\n")
247247
.append(" <td>\n");
248248
generateUnorderedListMethodVariants(

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

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@
7171
import com.google.api.generator.engine.ast.Variable;
7272
import com.google.api.generator.engine.ast.VariableExpr;
7373
import com.google.api.generator.engine.ast.WhileStatement;
74+
import com.google.api.generator.engine.writer.JavaFormatter.FormatException;
7475
import com.google.api.generator.gapic.composer.grpc.ServiceClientClassComposer;
7576
import com.google.api.generator.gapic.model.GapicClass;
7677
import com.google.api.generator.gapic.model.GapicContext;
@@ -960,6 +961,25 @@ public void writeJavaDocComment_specialChar() {
960961
assertEquals(expected, writerVisitor.write());
961962
}
962963

964+
@Test
965+
public void writeFailingComment_specialChar() {
966+
JavaDocComment javaDocComment =
967+
JavaDocComment.builder()
968+
.addUnescapedComment(
969+
"This resource reference needs to be CommentFormatted or it will fail: `bookShelves/*/`")
970+
.build();
971+
972+
FormatException exceptionForIncorrectlyFormattedComment =
973+
assertThrows(
974+
FormatException.class,
975+
() -> {
976+
javaDocComment.accept(writerVisitor);
977+
});
978+
assertThat(exceptionForIncorrectlyFormattedComment)
979+
.hasMessageThat()
980+
.contains("The input resource can not be parsed");
981+
}
982+
963983
@Test
964984
public void writeTernaryExpr_basic() {
965985
Variable conditionVariable =

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ import javax.annotation.Generated;
3838
* <th>Method Variants</th>
3939
* <tr>
4040
* <td>NestedMessageMethod</td>
41-
* <td><p></p></td>
41+
* <td><p> </td>
4242
* <td>
4343
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
4444
* <ul>

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ import javax.annotation.Generated;
3838
* <th>Method Variants</th>
3939
* <tr>
4040
* <td>GetBook</td>
41-
* <td><p></p></td>
41+
* <td><p> </td>
4242
* <td>
4343
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
4444
* <ul>

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ import javax.annotation.Generated;
3737
* <th>Method Variants</th>
3838
* <tr>
3939
* <td>FastFibonacci</td>
40-
* <td><p></p></td>
40+
* <td><p> </td>
4141
* <td>
4242
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
4343
* <ul>
@@ -51,7 +51,7 @@ import javax.annotation.Generated;
5151
* </tr>
5252
* <tr>
5353
* <td>SlowFibonacci</td>
54-
* <td><p></p></td>
54+
* <td><p> </td>
5555
* <td>
5656
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
5757
* <ul>

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

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ import javax.annotation.Generated;
5959
* <th>Method Variants</th>
6060
* <tr>
6161
* <td>Echo</td>
62-
* <td><p></p></td>
62+
* <td><p> </td>
6363
* <td>
6464
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
6565
* <ul>
@@ -84,7 +84,7 @@ import javax.annotation.Generated;
8484
* </tr>
8585
* <tr>
8686
* <td>Expand</td>
87-
* <td><p></p></td>
87+
* <td><p> </td>
8888
* <td>
8989
* <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>
9090
* <ul>
@@ -94,7 +94,7 @@ import javax.annotation.Generated;
9494
* </tr>
9595
* <tr>
9696
* <td>Collect</td>
97-
* <td><p></p></td>
97+
* <td><p> </td>
9898
* <td>
9999
* <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>
100100
* <ul>
@@ -104,7 +104,7 @@ import javax.annotation.Generated;
104104
* </tr>
105105
* <tr>
106106
* <td>Chat</td>
107-
* <td><p></p></td>
107+
* <td><p> </td>
108108
* <td>
109109
* <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>
110110
* <ul>
@@ -114,7 +114,7 @@ import javax.annotation.Generated;
114114
* </tr>
115115
* <tr>
116116
* <td>ChatAgain</td>
117-
* <td><p></p></td>
117+
* <td><p> </td>
118118
* <td>
119119
* <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>
120120
* <ul>
@@ -124,7 +124,7 @@ import javax.annotation.Generated;
124124
* </tr>
125125
* <tr>
126126
* <td>PagedExpand</td>
127-
* <td><p></p></td>
127+
* <td><p> </td>
128128
* <td>
129129
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
130130
* <ul>
@@ -139,7 +139,7 @@ import javax.annotation.Generated;
139139
* </tr>
140140
* <tr>
141141
* <td>SimplePagedExpand</td>
142-
* <td><p></p></td>
142+
* <td><p> </td>
143143
* <td>
144144
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
145145
* <ul>
@@ -158,7 +158,7 @@ import javax.annotation.Generated;
158158
* </tr>
159159
* <tr>
160160
* <td>Wait</td>
161-
* <td><p></p></td>
161+
* <td><p> </td>
162162
* <td>
163163
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
164164
* <ul>
@@ -178,7 +178,7 @@ import javax.annotation.Generated;
178178
* </tr>
179179
* <tr>
180180
* <td>Block</td>
181-
* <td><p></p></td>
181+
* <td><p> </td>
182182
* <td>
183183
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
184184
* <ul>
@@ -192,7 +192,7 @@ import javax.annotation.Generated;
192192
* </tr>
193193
* <tr>
194194
* <td>CollideName</td>
195-
* <td><p></p></td>
195+
* <td><p> </td>
196196
* <td>
197197
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
198198
* <ul>

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ import javax.annotation.Generated;
4747
* <th>Method Variants</th>
4848
* <tr>
4949
* <td>CreateUser</td>
50-
* <td><p></p></td>
50+
* <td><p> </td>
5151
* <td>
5252
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
5353
* <ul>
@@ -67,7 +67,7 @@ import javax.annotation.Generated;
6767
* </tr>
6868
* <tr>
6969
* <td>GetUser</td>
70-
* <td><p></p></td>
70+
* <td><p> </td>
7171
* <td>
7272
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
7373
* <ul>
@@ -86,7 +86,7 @@ import javax.annotation.Generated;
8686
* </tr>
8787
* <tr>
8888
* <td>UpdateUser</td>
89-
* <td><p></p></td>
89+
* <td><p> </td>
9090
* <td>
9191
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
9292
* <ul>
@@ -100,7 +100,7 @@ import javax.annotation.Generated;
100100
* </tr>
101101
* <tr>
102102
* <td>DeleteUser</td>
103-
* <td><p></p></td>
103+
* <td><p> </td>
104104
* <td>
105105
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
106106
* <ul>
@@ -119,7 +119,7 @@ import javax.annotation.Generated;
119119
* </tr>
120120
* <tr>
121121
* <td>ListUsers</td>
122-
* <td><p></p></td>
122+
* <td><p> </td>
123123
* <td>
124124
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
125125
* <ul>

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

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ import javax.annotation.Generated;
5454
* <th>Method Variants</th>
5555
* <tr>
5656
* <td>CreateRoom</td>
57-
* <td><p></p></td>
57+
* <td><p> </td>
5858
* <td>
5959
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
6060
* <ul>
@@ -72,7 +72,7 @@ import javax.annotation.Generated;
7272
* </tr>
7373
* <tr>
7474
* <td>GetRoom</td>
75-
* <td><p></p></td>
75+
* <td><p> </td>
7676
* <td>
7777
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
7878
* <ul>
@@ -91,7 +91,7 @@ import javax.annotation.Generated;
9191
* </tr>
9292
* <tr>
9393
* <td>UpdateRoom</td>
94-
* <td><p></p></td>
94+
* <td><p> </td>
9595
* <td>
9696
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
9797
* <ul>
@@ -105,7 +105,7 @@ import javax.annotation.Generated;
105105
* </tr>
106106
* <tr>
107107
* <td>DeleteRoom</td>
108-
* <td><p></p></td>
108+
* <td><p> </td>
109109
* <td>
110110
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
111111
* <ul>
@@ -124,7 +124,7 @@ import javax.annotation.Generated;
124124
* </tr>
125125
* <tr>
126126
* <td>ListRooms</td>
127-
* <td><p></p></td>
127+
* <td><p> </td>
128128
* <td>
129129
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
130130
* <ul>
@@ -139,7 +139,7 @@ import javax.annotation.Generated;
139139
* </tr>
140140
* <tr>
141141
* <td>CreateBlurb</td>
142-
* <td><p></p></td>
142+
* <td><p> </td>
143143
* <td>
144144
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
145145
* <ul>
@@ -162,7 +162,7 @@ import javax.annotation.Generated;
162162
* </tr>
163163
* <tr>
164164
* <td>GetBlurb</td>
165-
* <td><p></p></td>
165+
* <td><p> </td>
166166
* <td>
167167
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
168168
* <ul>
@@ -181,7 +181,7 @@ import javax.annotation.Generated;
181181
* </tr>
182182
* <tr>
183183
* <td>UpdateBlurb</td>
184-
* <td><p></p></td>
184+
* <td><p> </td>
185185
* <td>
186186
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
187187
* <ul>
@@ -195,7 +195,7 @@ import javax.annotation.Generated;
195195
* </tr>
196196
* <tr>
197197
* <td>DeleteBlurb</td>
198-
* <td><p></p></td>
198+
* <td><p> </td>
199199
* <td>
200200
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
201201
* <ul>
@@ -214,7 +214,7 @@ import javax.annotation.Generated;
214214
* </tr>
215215
* <tr>
216216
* <td>ListBlurbs</td>
217-
* <td><p></p></td>
217+
* <td><p> </td>
218218
* <td>
219219
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
220220
* <ul>
@@ -235,7 +235,7 @@ import javax.annotation.Generated;
235235
* </tr>
236236
* <tr>
237237
* <td>SearchBlurbs</td>
238-
* <td><p></p></td>
238+
* <td><p> </td>
239239
* <td>
240240
* <p>Request object method variants only take one parameter, a request object, which must be constructed before the call.</p>
241241
* <ul>
@@ -254,7 +254,7 @@ import javax.annotation.Generated;
254254
* </tr>
255255
* <tr>
256256
* <td>StreamBlurbs</td>
257-
* <td><p></p></td>
257+
* <td><p> </td>
258258
* <td>
259259
* <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>
260260
* <ul>
@@ -264,7 +264,7 @@ import javax.annotation.Generated;
264264
* </tr>
265265
* <tr>
266266
* <td>SendBlurbs</td>
267-
* <td><p></p></td>
267+
* <td><p> </td>
268268
* <td>
269269
* <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>
270270
* <ul>
@@ -274,7 +274,7 @@ import javax.annotation.Generated;
274274
* </tr>
275275
* <tr>
276276
* <td>Connect</td>
277-
* <td><p></p></td>
277+
* <td><p> </td>
278278
* <td>
279279
* <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>
280280
* <ul>

0 commit comments

Comments
 (0)