Dokka JSON: support for paragraphs, unordered lists, and links (#219)

* Support for paragrpahs and unordered lists in Dokka JSON

* Support for links in Dokka JSON

Author: fbenz

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

@@ -81,7 +81,7 @@ open class JsonOutputBuilder(
         val parameterComments = node.content.sections
                 .filter { it.subjectName != null }
                 .map {
-                    Pair(it.subjectName!!, extractContent(it))
+                    Pair(it.subjectName!!, extractContent(it, topLevel = true))
                 }.toMap()
         return Pair(node.name, MethodDocumentation(
                 comment = extractContent(node),
@@ -107,19 +107,49 @@ open class JsonOutputBuilder(
     }
 
     private fun extractContent(content: List<ContentNode>): String {
-        return content.joinToString("") { extractContent(it) }
+        return content.mapIndexed { index, it -> extractContent(it, topLevel = index == 0) }.joinToString("")
     }
 
-    private fun extractContent(content: ContentNode): String {
+    private fun extractContent(content: ContentNode, topLevel: Boolean): String {
         when (content) {
             is ContentText -> return content.text
-            is ContentBlock -> return content.children.joinToString("") { extractContent(it) }
-            is ContentNodeLink -> return content.node?.let { extractContent(it) } ?: ""
+            is ContentUnorderedList -> return wrap("<ul>", "</ul>", joinChildren(content))
+            is ContentListItem -> return listItem(content)
+            is ContentParagraph -> 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 ""
             else -> logger.warn("Unhandled content node: $content")
         }
         return ""
     }
+
+    private fun paragraph(paragraph: ContentParagraph, topLevel: Boolean): String {
+        return if (topLevel) {
+            // Ignore paragraphs on the top level
+            joinChildren(paragraph)
+        } else {
+            wrap("<p>", "</p>", joinChildren(paragraph))
+        }
+    }
+
+    private fun listItem(item: ContentListItem): String {
+        val child = item.children.singleOrNull()
+        return if (child is ContentParagraph) {
+            // Ignore paragraph if item is nested underneath an item
+            wrap("<li>", "</li>", joinChildren(child))
+        } else {
+            wrap("<li>", "</li>", joinChildren(item))
+        }
+    }
+
+    private fun wrap(prefix: String, suffix: String, body: String): String = "$prefix$body$suffix"
+
+    private fun joinChildren(block: ContentBlock): String = block.children.joinToString("") { extractContent(it, topLevel = false) }
 }
 
 open class JsonFormatService @Inject constructor(private val logger: DokkaLogger) : FormatService {

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

@@ -2,6 +2,13 @@
 
 /**
  * Javadoc on a Java class
+ * <p>
+ * Next paragraph
+ *
+ * <ul>
+ *     <li>Item 1</li>
+ *     <li>Item 2</li>
+ * </ul>
  */
 public class JavaClass {
 
@@ -19,7 +26,7 @@ public class JavaClass {
      *
      * @param a First param a
      * @param b Second param b
-     * @see JavaClass
+     * @see <a href="http://some-url.com">some link</a>
      * @deprecated Use something else
      * @title Custom tag
      */

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

@@ -1,5 +1,5 @@
 {
-  "comment" : "Javadoc on a Java class",
+  "comment" : "Javadoc on a Java class <p> Next paragraph </p><ul> <li>Item 1</li> <li>Item 2</li> </ul>",
   "fields" : {
     "someField" : {
       "comment" : "A Java field",
@@ -18,7 +18,7 @@
       },
       "tags" : {
         "parameters" : "Second param b",
-        "see" : "JavaClass",
+        "see" : "<a href=\"http://some-url.com\">some link</a>",
         "title" : "Custom tag"
       }
     }

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

@@ -1,5 +1,5 @@
 {
-  "comment" : "Class documentation",
+  "comment" : "Class documentation<p>Next paragraph</p><ul><li>Item 1</li><li>Item 2</li></ul>",
   "fields" : {
     "text" : {
       "comment" : "Documentation for text property",
@@ -16,7 +16,7 @@
   },
   "methods" : {
     "add" : {
-      "comment" : "Function add",
+      "comment" : "Function add<p><a href=\"http://some-url.com\">some link</a></p>",
       "parameters" : {
         "a" : "First param a",
         "b" : "Second param b"

spring-auto-restdocs-dokka-json/testdata/KotlinDataClass.kt

@@ -4,6 +4,11 @@ import java.math.BigDecimal
 
 /**
  * Class documentation
+ *
+ * Next paragraph
+ *
+ * * Item 1
+ * * Item 2
  */
 data class KotlinDataClass(
         /**
@@ -22,6 +27,8 @@ data class KotlinDataClass(
     /**
      * Function add
      *
+     * [some link](http://some-url.com)
+     *
      * @param a First param a
      * @param b Second param b
      * @see KotlinDataClass