diff --git a/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java b/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java index a19c5518d3..15374647f9 100644 --- a/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java +++ b/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java @@ -84,14 +84,17 @@ public Builder addComment(String comment) { return this; } + // TODO(developer):
and {@code} is not supporting rendering '@' character, it is evaluated
+ // as Javadoc tag. Please handle '@' character if need in the future. More details at
+ // https://reflectoring.io/howto-format-code-snippets-in-javadoc/#pre--code
public Builder addSampleCode(String sampleCode) {
- componentsList.add("");
+ componentsList.add("{@code");
Arrays.stream(sampleCode.split("\\r?\\n"))
.forEach(
line -> {
- componentsList.add(HtmlEscaper.process(line));
+ componentsList.add(line);
});
- componentsList.add("
");
+ componentsList.add("}");
return this;
}
diff --git a/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java b/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java
index b80014f6f8..967b5ad575 100644
--- a/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java
+++ b/src/test/java/com/google/api/generator/engine/ast/JavaDocCommentTest.java
@@ -46,10 +46,10 @@ public void createJavaDocComment_specialCharacter() {
+ "&\"\\f\n"
+ "`'{@literal @}*/\n"
+ "title: GetBigBook: <War and Peace>\n" - + "
\n"
- + "ApiFuture<Shelf> future ="
+ + "{@code\n"
+ + "ApiFuture future ="
+ " libraryClient.createShelfCallable().futureCall(request);\n"
- + " \n"
+ + "}\n"
+ "@throws Exception This is an exception.";
assertEquals(javaDocComment.comment(), expected);
}
@@ -62,12 +62,35 @@ public void createJavaDocComment_sampleCode() {
JavaDocComment.builder().addComment(comment).addSampleCode(sampleCode).build();
String expected =
"sample codes:\n"
- + "\n"
+ + "{@code\n"
+ "resource = project/{project}/shelfId/{shelfId}\n"
- + "";
+ + "}";
assertEquals(javaDocComment.comment(), expected);
}
+ @Test
+ public void createJavaDocComment_sampleCodePreserveIndentAndLineBreaks() {
+ String comment = "sample codes:";
+ String formattedSampleCode =
+ "SubscriptionAdminSettings subscriptionAdminSettings =\n"
+ + " SubscriptionAdminSettings.newBuilder().setEndpoint(myEndpoint).build();\n";
+ String badFormattingSampleCode =
+ "SubscriptionAdminSettings subscriptionAdminSettings =\n"
+ + " SubscriptionAdminSettings\n"
+ + " .newBuilder()\n"
+ + " .setEndpoint(myEndpoint)\n"
+ + " .build();\n";
+ JavaDocComment formattedJavaDoc =
+ JavaDocComment.builder().addComment(comment).addSampleCode(formattedSampleCode).build();
+ JavaDocComment badFormatJavaDoc =
+ JavaDocComment.builder().addComment(comment).addSampleCode(badFormattingSampleCode).build();
+ String expectedFormatted = comment.concat("\n{@code\n" + formattedSampleCode + "}");
+ String expectedBadFormat =
+ comment.concat("\n{@code\n" + badFormattingSampleCode + "}");
+ assertEquals(formattedJavaDoc.comment(), expectedFormatted);
+ assertEquals(badFormatJavaDoc.comment(), expectedBadFormat);
+ }
+
@Test
public void createJavaDocComment_multipleComments() {
// Add methods, like `addComment()`, should add components at any place,
@@ -198,4 +221,8 @@ public void createavaDocComment_allComponents() {
+ "@deprecated Use the {@link ArchivedBookName} class instead.";
assertEquals(javaDocComment.comment(), expected);
}
+
+ private static String createLines(int numLines) {
+ return new String(new char[numLines]).replace("\0", "%s");
+ }
}
diff --git a/src/test/java/com/google/api/generator/engine/goldens/JavaCodeGeneratorTest.golden b/src/test/java/com/google/api/generator/engine/goldens/JavaCodeGeneratorTest.golden
index c6fb279b8f..2dae06aa3f 100644
--- a/src/test/java/com/google/api/generator/engine/goldens/JavaCodeGeneratorTest.golden
+++ b/src/test/java/com/google/api/generator/engine/goldens/JavaCodeGeneratorTest.golden
@@ -26,9 +26,9 @@ import java.util.Stack;
/**
* Service Description: This is a test comment.
*
- *
+ * {@code
* LibraryServiceStub libServiceStub = new LibraryServiceStub()
- *
+ * }
*
* This class provides the ability to make remote calls to the backing service" + " through method calls that map to API methods. Sample code to get started:\n", - "*
\n",
+ "* {@code\n",
"* try (boolean condition = false) {\n",
"* int x = 3;\n",
"* }\n",
- "* \n",
+ "* }\n",
"* The surface of this class includes several types of Java methods for each of" + " the API's methods:\n", "*
\n",
+ "* {@code\n",
"* try (boolean condition = false) {\n",
"* int x = 3;\n",
"* }\n",
- "* \n",
+ "* }\n",
"* @param shelfName The name of the shelf where books are published to.\n",
"* @throws com.google.api.gax.rpc.ApiException if the remote call fails.\n",
"* @deprecated Use the {@link ArchivedBookName} class instead.\n",
@@ -627,10 +627,10 @@ public void writeJavaDocComment_specialChar() {
"/**\n",
"* The API has a collection of [Shelf][google.example.library.v1.Shelf] resources\n",
"* named `bookShelves/*`\n",
- "* \n",
- "* ApiFuture<Shelf> future ="
+ "* {@code\n",
+ "* ApiFuture future ="
+ " libraryClient.createShelfCallable().futureCall(request);\n",
- "* \n",
+ "* }\n",
"*