[composer][SampleCode]Update code mark for sample code snippet in Javadoc (#470)

summer-ji-eng · web-flow · commit a1cea1a7ca7f · 2020-11-13T17:17:01.000-08:00
* Update code mark for sample code snippet in Javadoc
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
@@ -84,14 +84,17 @@ public Builder addComment(String comment) {
       return this;
     }
 
+    // TODO(developer): <pre> 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("<pre><code>");
+      componentsList.add("<pre>{@code");
       Arrays.stream(sampleCode.split("\\r?\\n"))
           .forEach(
               line -> {
-                componentsList.add(HtmlEscaper.process(line));
+                componentsList.add(line);
               });
-      componentsList.add("</code></pre>");
+      componentsList.add("}</pre>");
       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
@@ -46,10 +46,10 @@ public void createJavaDocComment_specialCharacter() {
             + "&amp;\"\\f\n"
             + "`'{@literal @}&#42;/\n"
             + "<p> title: GetBigBook: &lt;War and Peace&gt;\n"
-            + "<pre><code>\n"
-            + "ApiFuture&lt;Shelf&gt; future ="
+            + "<pre>{@code\n"
+            + "ApiFuture<Shelf> future ="
             + " libraryClient.createShelfCallable().futureCall(request);\n"
-            + "</code></pre>\n"
+            + "}</pre>\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"
-            + "<pre><code>\n"
+            + "<pre>{@code\n"
             + "resource = project/{project}/shelfId/{shelfId}\n"
-            + "</code></pre>";
+            + "}</pre>";
     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<pre>{@code\n" + formattedSampleCode + "}</pre>");
+    String expectedBadFormat =
+        comment.concat("\n<pre>{@code\n" + badFormattingSampleCode + "}</pre>");
+    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
@@ -26,9 +26,9 @@ import java.util.Stack;
 /**
  * Service Description: This is a test comment.
  *
- * <pre><code>
+ * <pre>{@code
  * LibraryServiceStub libServiceStub = new LibraryServiceStub()
- * </code></pre>
+ * }</pre>
  *
  * <ol>
  *   <li>A "flattened" method.
diff --git a/src/test/java/com/google/api/generator/engine/writer/JavaWriterVisitorTest.java b/src/test/java/com/google/api/generator/engine/writer/JavaWriterVisitorTest.java
@@ -513,23 +513,23 @@ public void writeJavaDocCommentStatement_allComponents() {
             "* this is a test comment\n",
             "* <p> 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",
-            "* <pre><code>\n",
+            "* <pre>{@code\n",
             "* try (boolean condition = false) {\n",
             "* int x = 3;\n",
             "* }\n",
-            "* </code></pre>\n",
+            "* }</pre>\n",
             "* <p> The surface of this class includes several types of Java methods for each of"
                 + " the API's methods:\n",
             "* <ol>\n",
             "* <li> A flattened method.\n",
             "* <li>  A request object method.\n",
             "* <li> A callable method.\n",
             "* </ol>\n",
-            "* <pre><code>\n",
+            "* <pre>{@code\n",
             "* try (boolean condition = false) {\n",
             "* int x = 3;\n",
             "* }\n",
-            "* </code></pre>\n",
+            "* }</pre>\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/&#42;`\n",
-            "* <pre><code>\n",
-            "* ApiFuture&lt;Shelf&gt; future ="
+            "* <pre>{@code\n",
+            "* ApiFuture<Shelf> future ="
                 + " libraryClient.createShelfCallable().futureCall(request);\n",
-            "* </code></pre>\n",
+            "* }</pre>\n",
             "* <ol>\n",
             "* <li> A \"flattened\" method.\n",
             "* <li> A \"request object\" method.\n",

Original file line number	Diff line number	Diff line change
`@@ -26,9 +26,9 @@ import java.util.Stack;`
`26`	`26`	`/**`
`27`	`27`	`* Service Description: This is a test comment.`
`28`	`28`	`*`
`29`		`- * <pre><code>`
	`29`	`+ * <pre>{@code`
`30`	`30`	`* LibraryServiceStub libServiceStub = new LibraryServiceStub()`
`31`		`- * </code></pre>`
	`31`	`+ * }</pre>`
`32`	`32`	`*`
`33`	`33`	`* <ol>`
`34`	`34`	`* <li>A "flattened" method.`