KDoc: Add support for bold, italics, and code (#387)

* KDoc: Add support for bold, italics, and code

* Also handle strong and em

* Demonstrate formatting in the Java example

Author: fbenz

samples/java-webmvc/generated-docs/index.html

@@ -1109,10 +1109,13 @@ <h3 id="resources-item-resource-test-add-item"><a class="anchor" href="#resource
 <p><code>POST /items</code></p>
 </div>
 <div class="paragraph">
-<p>Adds new item.</p>
+<p>Adds a new <strong>item</strong>.</p>
 </div>
 <div class="paragraph">
-<p>An example of accepting a custom type as request body and returning a {@link ResponseEntity}.</p>
+<p>An <em>example</em> of accepting a custom type as request body and returning a {@link ResponseEntity}.</p>
+</div>
+<div class="paragraph">
+<p><code>someCode("foo")</code>.</p>
 </div>
 <div class="sect3">
 <h4 id="_authorization_3"><a class="anchor" href="#_authorization_3"></a><a class="link" href="#_authorization_3">2.3.1. Authorization</a></h4>
@@ -1236,7 +1239,7 @@ <h4 id="_example_request"><a class="anchor" href="#_example_request"></a><a clas
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl 'http://localhost:8080/items' -i -X POST \
     -H 'Content-Type: application/json' \
-    -H 'Authorization: Bearer 0b765e43-cb96-4f00-b747-af7e62590e11' \
+    -H 'Authorization: Bearer 5f5cb4c9-67a4-44da-bf06-e7d299ed9287' \
     -d '{"description":"Hot News"}'</code></pre>
 </div>
 </div>
@@ -1539,7 +1542,7 @@ <h4 id="_example_request_2"><a class="anchor" href="#_example_request_2"></a><a
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X PUT \
     -H 'Content-Type: application/json' \
-    -H 'Authorization: Bearer 0b765e43-cb96-4f00-b747-af7e62590e11' \
+    -H 'Authorization: Bearer 5f5cb4c9-67a4-44da-bf06-e7d299ed9287' \
     -d '{"description":"Hot News"}'</code></pre>
 </div>
 </div>
@@ -1663,7 +1666,7 @@ <h4 id="_example_request_3"><a class="anchor" href="#_example_request_3"></a><a
 <div class="listingblock">
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X DELETE \
-    -H 'Authorization: Bearer 0b765e43-cb96-4f00-b747-af7e62590e11'</code></pre>
+    -H 'Authorization: Bearer 5f5cb4c9-67a4-44da-bf06-e7d299ed9287'</code></pre>
 </div>
 </div>
 </div>
@@ -2228,15 +2231,15 @@ <h4 id="_example_response_5"><a class="anchor" href="#_example_response_5"></a><
   "totalElements" : 1,
   "last" : true,
   "size" : 20,
+  "numberOfElements" : 1,
+  "first" : true,
   "number" : 0,
   "sort" : {
     "orders" : [ ],
     "sorted" : false,
     "unsorted" : true,
     "empty" : true
   },
-  "numberOfElements" : 1,
-  "first" : true,
   "empty" : false
 }</code></pre>
 </div>
@@ -3527,7 +3530,7 @@ <h4 id="_example_response_12"><a class="anchor" href="#_example_response_12"></a
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2020-02-10 13:59:32 +0100
+Last updated 2020-04-12 14:15:02 +0200
 </div>
 </div>
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/styles/github.min.css">

samples/java-webmvc/src/main/java/capital/scalable/restdocs/example/items/ItemResource.java

@@ -108,9 +108,11 @@ public ItemResponse[] allItems() {
     }
 
     /**
-     * Adds new item.
+     * Adds a new <b>item</b>.
      * <p>
-     * An example of accepting a custom type as request body and returning a {@link ResponseEntity}.
+     * An <i>example</i> of accepting a custom type as request body and returning a {@link ResponseEntity}.
+     * <p>
+     * <code>someCode("foo")</code>
      *
      * @param itemUpdate Item information
      * @return response

samples/kotlin-webmvc/generated-docs/index.html

@@ -1073,10 +1073,13 @@ <h3 id="resources-item-resource-test-add-item"><a class="anchor" href="#resource
 <p><code>POST /items</code></p>
 </div>
 <div class="paragraph">
-<p>Adds new item.</p>
+<p>Adds a new <strong>item</strong>.</p>
 </div>
 <div class="paragraph">
-<p>An example of accepting a custom type as request body and returning a ResponseEntity.</p>
+<p>An <em>example</em> of accepting a custom type as request body and returning a ResponseEntity.</p>
+</div>
+<div class="paragraph">
+<p><code>someCode("foo")</code></p>
 </div>
 <div class="sect3">
 <h4 id="_authorization_3"><a class="anchor" href="#_authorization_3"></a><a class="link" href="#_authorization_3">2.3.1. Authorization</a></h4>
@@ -1186,7 +1189,7 @@ <h4 id="_example_request"><a class="anchor" href="#_example_request"></a><a clas
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl 'http://localhost:8080/items' -i -X POST \
     -H 'Content-Type: application/json' \
-    -H 'Authorization: Bearer e75106d3-5eb2-456f-9d98-f0d516990b01' \
+    -H 'Authorization: Bearer 81c803fa-adc9-4c33-8d7f-d460882862a3' \
     -d '{"description":"Hot News"}'</code></pre>
 </div>
 </div>
@@ -1468,7 +1471,7 @@ <h4 id="_example_request_2"><a class="anchor" href="#_example_request_2"></a><a
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X PUT \
     -H 'Content-Type: application/json' \
-    -H 'Authorization: Bearer e75106d3-5eb2-456f-9d98-f0d516990b01' \
+    -H 'Authorization: Bearer 81c803fa-adc9-4c33-8d7f-d460882862a3' \
     -d '{"description":"Hot News"}'</code></pre>
 </div>
 </div>
@@ -1576,7 +1579,7 @@ <h4 id="_example_request_3"><a class="anchor" href="#_example_request_3"></a><a
 <div class="listingblock">
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X DELETE \
-    -H 'Authorization: Bearer e75106d3-5eb2-456f-9d98-f0d516990b01'</code></pre>
+    -H 'Authorization: Bearer 81c803fa-adc9-4c33-8d7f-d460882862a3'</code></pre>
 </div>
 </div>
 </div>
@@ -2089,22 +2092,22 @@ <h4 id="_example_response_5"><a class="anchor" href="#_example_response_5"></a><
     "offset" : 0,
     "pageNumber" : 0,
     "pageSize" : 20,
-    "paged" : true,
-    "unpaged" : false
+    "unpaged" : false,
+    "paged" : true
   },
   "total" : 1,
+  "totalElements" : 1,
   "totalPages" : 1,
   "last" : true,
-  "totalElements" : 1,
   "size" : 20,
-  "numberOfElements" : 1,
+  "number" : 0,
   "sort" : {
     "orders" : [ ],
     "sorted" : false,
     "unsorted" : true,
     "empty" : true
   },
-  "number" : 0,
+  "numberOfElements" : 1,
   "first" : true,
   "empty" : false
 }</code></pre>
@@ -2766,7 +2769,7 @@ <h4 id="_example_requestresponse_3"><a class="anchor" href="#_example_requestres
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2020-02-10 13:52:46 +0100
+Last updated 2020-04-12 14:15:02 +0200
 </div>
 </div>
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/styles/github.min.css">

samples/kotlin-webmvc/src/main/java/capital/scalable/restdocs/example/items/ItemResource.kt

@@ -85,10 +85,11 @@ internal class ItemResource {
     fun allItems() = arrayOf(ITEM, CHILD)
 
     /**
-     * Adds new item.
+     * Adds a new **item**.
      *
+     * An *example* of accepting a custom type as request body and returning a [ResponseEntity].
      *
-     * An example of accepting a custom type as request body and returning a [ResponseEntity].
+     * `someCode("foo")`
      *
      * @param itemUpdate Item information
      * @return response

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/javadoc/JavadocUtil.java

@@ -7,9 +7,9 @@
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- *
+ * 
  *      http://www.apache.org/licenses/LICENSE-2.0
- *
+ * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -45,8 +45,14 @@ public static String convertFromJavadoc(String javadoc, TemplateFormatting templ
                 .replace("</li>", "")
                 .replace("<b>", templateFormatting.getBold())
                 .replace("</b>", templateFormatting.getBold())
+                .replace("<strong>", templateFormatting.getBold())
+                .replace("</strong>", templateFormatting.getBold())
                 .replace("<i>", templateFormatting.getItalics())
                 .replace("</i>", templateFormatting.getItalics())
+                .replace("<em>", templateFormatting.getItalics())
+                .replace("</em>", templateFormatting.getItalics())
+                .replace("<code>", templateFormatting.getCode())
+                .replace("</code>", templateFormatting.getCode())
                 .replaceAll("<a\\s+href\\s*=\\s*[\"\'](.*?)[\"\']\\s*>(.*?)</a>",
                         templateFormatting.link());
 

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/util/TemplateFormatting.java

@@ -7,9 +7,9 @@
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- *
+ * 
  *      http://www.apache.org/licenses/LICENSE-2.0
- *
+ * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -26,24 +26,28 @@ public class TemplateFormatting {
     private static final String BOLD_MD = "**";
     private static final String ITALICS_ADOC = "__";
     private static final String ITALICS_MD = "*";
+    private static final String CODE_ADOC = "`";
+    private static final String CODE_MD = "`";
     private static final String LINK_ADOC = "link:$1[$2]";
     private static final String LINK_MD = "[$2]($1)";
 
     public static TemplateFormatting ASCIIDOC =
-            new TemplateFormatting(LINE_BREAK_ADOC, BOLD_ADOC, ITALICS_ADOC, LINK_ADOC);
+            new TemplateFormatting(LINE_BREAK_ADOC, BOLD_ADOC, ITALICS_ADOC, CODE_ADOC, LINK_ADOC);
 
     public static TemplateFormatting MARKDOWN =
-            new TemplateFormatting(LINE_BREAK_MD, BOLD_MD, ITALICS_MD, LINK_MD);
+            new TemplateFormatting(LINE_BREAK_MD, BOLD_MD, ITALICS_MD, CODE_MD, LINK_MD);
 
     private final String lineBreak;
     private final String bold;
     private final String italics;
+    private final String code;
     private final String link;
 
-    private TemplateFormatting(String lineBreak, String bold, String italics, String link) {
+    private TemplateFormatting(String lineBreak, String bold, String italics, String code, String link) {
         this.lineBreak = lineBreak;
         this.bold = bold;
         this.italics = italics;
+        this.code = code;
         this.link = link;
     }
 
@@ -59,6 +63,10 @@ public String getItalics() {
         return italics;
     }
 
+    public String getCode() {
+        return code;
+    }
+
     public String link() {
         return link;
     }

spring-auto-restdocs-core/src/test/java/capital/scalable/restdocs/javadoc/JavadocUtilTest.java

@@ -7,9 +7,9 @@
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- *
+ * 
  *      http://www.apache.org/licenses/LICENSE-2.0
- *
+ * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -108,17 +108,49 @@ public void convertBulletedListMarkdown() {
     }
 
     @Test
-    public void convertStylingAsciidoc() {
-        String actual = "<b>bold</b>normal<i>italics</i>";
-        String expected = "**bold**normal__italics__";
+    public void convertBoldStylingAsciidoc() {
+        String actual = "before<b>bold</b>normal<strong>bold2</strong>after";
+        String expected = "before**bold**normal**bold2**after";
         assertThat(JavadocUtil.convertFromJavadoc(actual, TemplateFormatting.ASCIIDOC),
                 is(expected));
     }
 
     @Test
-    public void convertStylingMarkdown() {
-        String actual = "<b>bold</b>normal<i>italics</i>";
-        String expected = "**bold**normal*italics*";
+    public void convertItalicsStylingAsciidoc() {
+        String actual = "before<i>italics</i>normal<em>italics2</em>after";
+        String expected = "before__italics__normal__italics2__after";
+        assertThat(JavadocUtil.convertFromJavadoc(actual, TemplateFormatting.ASCIIDOC),
+                is(expected));
+    }
+
+    @Test
+    public void convertCodeStylingAsciidoc() {
+        String actual = "before <code>code()</code> after";
+        String expected = "before `code()` after";
+        assertThat(JavadocUtil.convertFromJavadoc(actual, TemplateFormatting.ASCIIDOC),
+                is(expected));
+    }
+
+    @Test
+    public void convertBoldStylingMarkdown() {
+        String actual = "before<b>bold</b>normal<strong>bold2</strong>after";
+        String expected = "before**bold**normal**bold2**after";
+        assertThat(JavadocUtil.convertFromJavadoc(actual, TemplateFormatting.MARKDOWN),
+                is(expected));
+    }
+
+    @Test
+    public void convertItalicsStylingMarkdown() {
+        String actual = "before<i>italics</i>normal<em>italics2</em>after";
+        String expected = "before*italics*normal*italics2*after";
+        assertThat(JavadocUtil.convertFromJavadoc(actual, TemplateFormatting.MARKDOWN),
+                is(expected));
+    }
+
+    @Test
+    public void convertCodeStylingMarkdown() {
+        String actual = "before <code>code()</code> after";
+        String expected = "before `code()` after";
         assertThat(JavadocUtil.convertFromJavadoc(actual, TemplateFormatting.MARKDOWN),
                 is(expected));
     }

spring-auto-restdocs-dokka-json/src/main/kotlin/capital/scalable/dokka/json/JsonFormatService.kt

@@ -127,22 +127,28 @@ open class JsonOutputBuilder(
     private fun extractContent(content: ContentNode, topLevel: Boolean): String {
         when (content) {
             is ContentText -> return content.text
+            is ContentEmphasis -> return wrap("<i>", "</i>", joinChildren(content))
+            is ContentStrong -> return wrap("<b>", "</b>", joinChildren(content))
+            is ContentCode -> return wrap("<code>", "</code>", joinChildren(content))
             is ContentUnorderedList -> return wrap("<ul>", "</ul>", joinChildren(content))
             is ContentListItem -> return listItem(content)
             is ContentParagraph -> return paragraph(content, topLevel)
+            is ContentSection -> return paragraph(content, topLevel)
             is ContentExternalLink -> return "<a href=\"${content.href}\">${joinChildren(content)}</a>"
             // Ignore href of references to other code parts and just show the link text, e.g. class name.
             is ContentNodeLink -> return joinChildren(content)
             // Fallback. Some of the content types above are derived from ContentBlock and
             // thus this one has to be after them.
             is ContentBlock -> return joinChildren(content)
             is ContentEmpty -> return ""
+            is ContentSymbol -> return ""
+            is NodeRenderContent -> return ""
             else -> logger.warn("Unhandled content node: $content")
         }
         return ""
     }
 
-    private fun paragraph(paragraph: ContentParagraph, topLevel: Boolean): String {
+    private fun paragraph(paragraph: ContentBlock, topLevel: Boolean): String {
         return if (topLevel) {
             // Ignore paragraphs on the top level
             joinChildren(paragraph)

spring-auto-restdocs-dokka-json/testdata/JavaClass.java

@@ -4,7 +4,7 @@
  * Javadoc on a Java class
  * <p>
  * Next paragraph
- *
+ * UTF 8 test: 我能吞下玻璃而不伤身体。Árvíztűrő tükörfúrógép
  * <ul>
  *     <li>Item 1</li>
  *     <li>Item 2</li>

spring-auto-restdocs-dokka-json/testdata/JavaClass.json

@@ -1,5 +1,5 @@
 {
-  "comment" : "Javadoc on a Java class<p>Next paragraph</p><ul><li>Item 1</li> <li>Item 2</li></ul>",
+  "comment" : "Javadoc on a Java class<p>Next paragraph UTF 8 test: 我能吞下玻璃而不伤身体。Árvíztűrő tükörfúrógép</p><ul><li>Item 1</li> <li>Item 2</li></ul>",
   "fields" : {
     "someField" : {
       "comment" : "A Java field",