Rewrite output generation; much cleaner Markdown and HTML generated. Resolves #71, #72

89 files changed, 658 insertions, 848 deletions

diff --git a/core/src/main/kotlin/Formats/GFMFormatService.kt b/core/src/main/kotlin/Formats/GFMFormatService.kt
index b57fa932..cfb7fc03 100644
--- a/core/src/main/kotlin/Formats/GFMFormatService.kt
+++ b/core/src/main/kotlin/Formats/GFMFormatService.kt
@@ -9,11 +9,38 @@ open class GFMOutputBuilder(to: StringBuilder,
                                  extension: String)
     : MarkdownOutputBuilder(to, location, locationService, languageService, extension)
 {
-    override fun appendTable(to: StringBuilder, vararg columns: String, body: () -> Unit) {
+    override fun appendTable(vararg columns: String, body: () -> Unit) {
         to.appendln(columns.joinToString(" | ", "| ", " |"))
         to.appendln("|" + "---|".repeat(columns.size))
         body()
     }
+
+    override fun appendUnorderedList(body: () -> Unit) {
+        if (inTableCell) {
+            wrapInTag("ul", body)
+        }
+        else {
+            super.appendUnorderedList(body)
+        }
+    }
+
+    override fun appendOrderedList(body: () -> Unit) {
+        if (inTableCell) {
+            wrapInTag("ol", body)
+        }
+        else {
+            super.appendOrderedList(body)
+        }
+    }
+
+    override fun appendListItem(body: () -> Unit) {
+        if (inTableCell) {
+            wrapInTag("li", body)
+        }
+        else {
+            super.appendListItem(body)
+        }
+    }
 }
 
 open class GFMFormatService(locationService: LocationService,
diff --git a/core/src/main/kotlin/Formats/HtmlFormatService.kt b/core/src/main/kotlin/Formats/HtmlFormatService.kt
index fff8f553..de41d4c6 100644
--- a/core/src/main/kotlin/Formats/HtmlFormatService.kt
+++ b/core/src/main/kotlin/Formats/HtmlFormatService.kt
@@ -14,108 +14,77 @@ open class HtmlOutputBuilder(to: StringBuilder,
                              val templateService: HtmlTemplateService)
     : StructuredOutputBuilder(to, location, locationService, languageService, extension)
 {
-    override fun formatText(text: String): String {
-        return text.htmlEscape()
+    override fun appendText(text: String) {
+        to.append(text.htmlEscape())
     }
 
-    override fun formatSymbol(text: String): String {
-        return "<span class=\"symbol\">${formatText(text)}</span>"
+    override fun appendSymbol(text: String) {
+        to.append("<span class=\"symbol\">${text.htmlEscape()}</span>")
     }
 
-    override fun formatKeyword(text: String): String {
-        return "<span class=\"keyword\">${formatText(text)}</span>"
+    override fun appendKeyword(text: String) {
+        to.append("<span class=\"keyword\">${text.htmlEscape()}</span>")
     }
 
-    override fun formatIdentifier(text: String, kind: IdentifierKind, signature: String?): String {
+    override fun appendIdentifier(text: String, kind: IdentifierKind, signature: String?) {
         val id = signature?.let { " id=\"$it\"" }.orEmpty()
-        return "<span class=\"identifier\"$id>${formatText(text)}</span>"
+        to.append("<span class=\"identifier\"$id>${text.htmlEscape()}</span>")
     }
 
-    override fun appendBlockCode(to: StringBuilder, lines: List<String>, language: String) {
-        to.append("<pre><code>")
-        to.append(lines.joinToString("\n"))
-        to.append("</code></pre>")
-    }
-
-    override fun appendHeader(to: StringBuilder, text: String, level: Int) {
-        to.appendln("<h$level>${text}</h$level>")
-    }
+    override fun appendBlockCode(language: String, body: () -> Unit) = wrap("<pre><code>", "</code></pre>", body)
 
-    override fun appendParagraph(to: StringBuilder, text: String) {
-        to.appendln("<p>${text}</p>")
-    }
+    override fun appendHeader(level: Int, body: () -> Unit) =
+        wrapInTag("h$level", body, newlineBeforeOpen = true, newlineAfterClose = true)
+    override fun appendParagraph(body: () -> Unit) =
+        wrapInTag("p", body, newlineBeforeOpen = true, newlineAfterClose = true)
 
-    override fun appendLine(to: StringBuilder, text: String) {
-        to.appendln("$text<br/>")
+    override fun appendLine() {
+        to.appendln("<br/>")
     }
 
-    override fun appendAnchor(to: StringBuilder, anchor: String) {
+    override fun appendAnchor(anchor: String) {
         to.appendln("<a name=\"${anchor.htmlEscape()}\"></a>")
     }
 
-    override fun appendTable(to: StringBuilder, vararg columns: String, body: () -> Unit) {
-        to.appendln("<table>")
-        body()
-        to.appendln("</table>")
-    }
-
-    override fun appendTableBody(to: StringBuilder, body: () -> Unit) {
-        to.appendln("<tbody>")
-        body()
-        to.appendln("</tbody>")
-    }
-
-    override fun appendTableRow(to: StringBuilder, body: () -> Unit) {
-        to.appendln("<tr>")
-        body()
-        to.appendln("</tr>")
-    }
-
-    override fun appendTableCell(to: StringBuilder, body: () -> Unit) {
-        to.appendln("<td>")
-        body()
-        to.appendln("</td>")
-    }
-
-    override fun formatLink(text: String, href: String): String {
-        return "<a href=\"${href}\">${text}</a>"
-    }
-
-    override fun formatStrong(text: String): String {
-        return "<strong>${text}</strong>"
-    }
-
-    override fun formatEmphasis(text: String): String {
-        return "<emph>${text}</emph>"
-    }
+    override fun appendTable(vararg columns: String, body: () -> Unit) =
+            wrapInTag("table", body, newlineAfterOpen = true, newlineAfterClose = true)
+    override fun appendTableBody(body: () -> Unit) =
+            wrapInTag("tbody", body, newlineAfterOpen = true, newlineAfterClose = true)
+    override fun appendTableRow(body: () -> Unit) =
+            wrapInTag("tr", body, newlineAfterOpen = true, newlineAfterClose = true)
+    override fun appendTableCell(body: () -> Unit) =
+            wrapInTag("td", body, newlineAfterOpen = true, newlineAfterClose = true)
 
-    override fun formatStrikethrough(text: String): String {
-        return "<s>${text}</s>"
-    }
+    override fun appendLink(href: String, body: () -> Unit) = wrap("<a href=\"$href\">", "</a>", body)
 
-    override fun formatCode(code: String): String {
-        return "<code>${code}</code>"
-    }
+    override fun appendStrong(body: () -> Unit) = wrapInTag("strong", body)
+    override fun appendEmphasis(body: () -> Unit) = wrapInTag("emph", body)
+    override fun appendStrikethrough(body: () -> Unit) = wrapInTag("s", body)
+    override fun appendCode(body: () -> Unit) = wrapInTag("code", body)
 
-    override fun formatUnorderedList(text: String): String = "<ul>${text}</ul>"
-    override fun formatOrderedList(text: String): String = "<ol>${text}</ol>"
+    override fun appendUnorderedList(body: () -> Unit) = wrapInTag("ul", body, newlineAfterClose = true)
+    override fun appendOrderedList(body: () -> Unit) = wrapInTag("ol", body, newlineAfterClose = true)
+    override fun appendListItem(body: () -> Unit) = wrapInTag("li", body, newlineAfterClose = true)
 
-    override fun formatListItem(text: String, kind: ListKind): String {
-        return "<li>${text}</li>"
+    override fun appendBreadcrumbSeparator() {
+        to.append("&nbsp;/&nbsp;")
     }
 
-    override fun formatBreadcrumbs(items: Iterable<FormatLink>): String {
-        return items.map { formatLink(it) }.joinToString("&nbsp;/&nbsp;")
-    }
-
-
     override fun appendNodes(nodes: Iterable<DocumentationNode>) {
         templateService.appendHeader(to, getPageTitle(nodes), locationService.calcPathToRoot(location))
         super.appendNodes(nodes)
         templateService.appendFooter(to)
     }
 
-    override fun formatNonBreakingSpace(): String = "&nbsp;"
+    override fun appendNonBreakingSpace() {
+        to.append("&nbsp;")
+    }
+
+    override fun ensureParagraph() {
+        if (!to.endsWith("<p>") && !to.endsWith("</p>")) {
+            to.append("\n<p>")
+        }
+    }
 }
 
 open class HtmlFormatService @Inject constructor(@Named("folders") locationService: LocationService,
@@ -143,8 +112,9 @@ open class HtmlFormatService @Inject constructor(@Named("folders") locationServi
     override fun appendOutlineHeader(location: Location, node: DocumentationNode, to: StringBuilder) {
         val link = ContentNodeDirectLink(node)
         link.append(languageService.render(node, LanguageService.RenderMode.FULL))
-        val signature = createOutputBuilder(to, location).formatText(location, link)
-        to.appendln("<a href=\"${location.path}\">${signature}</a><br/>")
+        val tempBuilder = StringBuilder()
+        createOutputBuilder(tempBuilder, location).appendContent(link)
+        to.appendln("<a href=\"${location.path}\">${tempBuilder.toString()}</a><br/>")
     }
 
     override fun appendOutlineLevel(to: StringBuilder, body: () -> Unit) {
diff --git a/core/src/main/kotlin/Formats/HtmlTemplateService.kt b/core/src/main/kotlin/Formats/HtmlTemplateService.kt
index 13587b05..7efb94a1 100644
--- a/core/src/main/kotlin/Formats/HtmlTemplateService.kt
+++ b/core/src/main/kotlin/Formats/HtmlTemplateService.kt
@@ -10,6 +10,9 @@ interface HtmlTemplateService {
         fun default(css: String? = null): HtmlTemplateService {
             return object : HtmlTemplateService {
                 override fun appendFooter(to: StringBuilder) {
+                    if (!to.endsWith('\n')) {
+                        to.append('\n')
+                    }
                     to.appendln("</BODY>")
                     to.appendln("</HTML>")
                 }
diff --git a/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt b/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt
index e3229523..03cf7fc8 100644
--- a/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt
+++ b/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt
@@ -18,21 +18,17 @@ class KotlinWebsiteOutputBuilder(to: StringBuilder,
         to.appendln("layout: api")
     }
 
-    override fun formatBreadcrumbs(items: Iterable<FormatLink>): String {
-        items.drop(1)
-
-        if (items.count() > 1) {
-            return "<div class='api-docs-breadcrumbs'>" +
-                    items.map { formatLink(it) }.joinToString(" / ") +
-                    "</div>"
+    override fun appendBreadcrumbs(path: Iterable<FormatLink>) {
+        if (path.count() > 1) {
+            to.append("<div class='api-docs-breadcrumbs'>")
+            super.appendBreadcrumbs(path)
+            to.append("</div>")
         }
-
-        return ""
     }
 
-    override fun formatCode(code: String): String = if (code.length > 0) "<code>$code</code>" else ""
+    override fun appendCode(body: () -> Unit) = wrapIfNotEmpty("<code>", "</code>", body)
 
-    override fun formatStrikethrough(text: String): String = "<s>$text</s>"
+    override fun appendStrikethrough(body: () -> Unit) = wrapInTag("s", body)
 
     private fun div(to: StringBuilder, cssClass: String, block: () -> Unit) {
         to.append("<div class=\"$cssClass\">")
@@ -42,7 +38,7 @@ class KotlinWebsiteOutputBuilder(to: StringBuilder,
         to.append("</div>\n")
     }
 
-    override fun appendAsSignature(to: StringBuilder, node: ContentNode, block: () -> Unit) {
+    override fun appendAsSignature(node: ContentNode, block: () -> Unit) {
         val contentLength = node.textLength
         if (contentLength == 0) return
         div(to, "signature") {
@@ -60,84 +56,81 @@ class KotlinWebsiteOutputBuilder(to: StringBuilder,