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()
- * 
+ * }
* *
    *
  1. 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 index 98379fac93..4c7135ed84 100644 --- 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,11 +513,11 @@ public void writeJavaDocCommentStatement_allComponents() { "* this is a test comment\n", "*

    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", @@ -525,11 +525,11 @@ public void writeJavaDocCommentStatement_allComponents() { "*
    1. A request object method.\n", "*
    2. A callable method.\n", "*
    \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", "*
      \n", "*
    1. A \"flattened\" method.\n", "*
    2. A \"request object\" method.\n",