From cd7084ddc4e6e7f32a35d265bfb1307fdaf27011 Mon Sep 17 00:00:00 2001
From: Ilya Ryzhenkov <orangy@jetbrains.com>
Date: Mon, 14 Jul 2014 21:15:04 +0400
Subject: Refactor to multiple-nodes formatting, implement smarter markdown
 format service.

---
 src/Formats/FormatService.kt         |   4 +-
 src/Formats/HtmlFormatService.kt     |  94 +++++++++++++++---------------
 src/Formats/MarkdownFormatService.kt | 109 ++++++++++++++++++++++++++---------
 src/Formats/TextFormatService.kt     |  22 +++----
 4 files changed, 143 insertions(+), 86 deletions(-)

diff --git a/src/Formats/FormatService.kt b/src/Formats/FormatService.kt
index 9e36c400..3708e9a7 100644
--- a/src/Formats/FormatService.kt
+++ b/src/Formats/FormatService.kt
@@ -2,7 +2,7 @@ package org.jetbrains.dokka
 
 public trait FormatService {
     val extension: String
-    fun format(node: DocumentationNode, to: StringBuilder)
+    fun format(nodes: Iterable<DocumentationNode>, to: StringBuilder)
 }
 
-fun FormatService.format(node: DocumentationNode): String = StringBuilder { format(node, this) }.toString()
\ No newline at end of file
+fun FormatService.format(node: Iterable<DocumentationNode>): String = StringBuilder { format(node, this) }.toString()
\ No newline at end of file
diff --git a/src/Formats/HtmlFormatService.kt b/src/Formats/HtmlFormatService.kt
index 4a0bca6f..f3d71215 100644
--- a/src/Formats/HtmlFormatService.kt
+++ b/src/Formats/HtmlFormatService.kt
@@ -3,60 +3,62 @@ package org.jetbrains.dokka
 public class HtmlFormatService(val locationService: LocationService,
                                val signatureGenerator: SignatureGenerator) : FormatService {
     override val extension: String = "html"
-    override fun format(node: DocumentationNode, to: StringBuilder) {
-        with (to) {
-            appendln("<h2>")
-            appendln("Summary for ${node.name}")
-            appendln("</h2>")
-            appendln("<code>")
-            appendln(signatureGenerator.render(node))
-            appendln("</code>")
-            appendln()
-            appendln("<p>")
-            appendln(node.doc.summary)
-            appendln("</p>")
-            appendln("<hr/>")
-
-            for (section in node.doc.sections) {
-                appendln("<h3>")
-                appendln(section.label)
-                appendln("</h3>")
+    override fun format(nodes: Iterable<DocumentationNode>, to: StringBuilder) {
+        for (node in nodes) {
+            with (to) {
+                appendln("<h2>")
+                appendln("Summary for ${node.name}")
+                appendln("</h2>")
+                appendln("<code>")
+                appendln(signatureGenerator.render(node))
+                appendln("</code>")
+                appendln()
                 appendln("<p>")
-                appendln(section.text)
+                appendln(node.doc.summary)
                 appendln("</p>")
-            }
+                appendln("<hr/>")
 
-            appendln("<h3>")
-            appendln("Members")
-            appendln("</h3>")
-            appendln("<table>")
+                for (section in node.doc.sections) {
+                    appendln("<h3>")
+                    appendln(section.label)
+                    appendln("</h3>")
+                    appendln("<p>")
+                    appendln(section.text)
+                    appendln("</p>")
+                }
 
-            appendln("<thead>")
-            appendln("<tr>")
-            appendln("<td>Member</td>")
-            appendln("<td>Signature</td>")
-            appendln("<td>Summary</td>")
-            appendln("</tr>")
-            appendln("</thead>")
+                appendln("<h3>")
+                appendln("Members")
+                appendln("</h3>")
+                appendln("<table>")
 
-            appendln("<tbody>")
-            for (member in node.members.sortBy { it.name }) {
-                val relativePath = locationService.relativeLocation(node, member, extension)
+                appendln("<thead>")
                 appendln("<tr>")
-                appendln("<td>")
-                append("<a href=\"${relativePath}\">${member.name}</a>")
-                appendln("</td>")
-                appendln("<td>")
-                append("${signatureGenerator.render(member)}")
-                appendln("</td>")
-                appendln("<td>")
-                append("${member.doc.summary}")
-                appendln("</td>")
+                appendln("<td>Member</td>")
+                appendln("<td>Signature</td>")
+                appendln("<td>Summary</td>")
                 appendln("</tr>")
-            }
-            appendln("</tbody>")
-            appendln("</table>")
+                appendln("</thead>")
 
+                appendln("<tbody>")
+                for (member in node.members.sortBy { it.name }) {
+                    val relativePath = locationService.relativeLocation(node, member, extension)
+                    appendln("<tr>")
+                    appendln("<td>")
+                    append("<a href=\"${relativePath}\">${member.name}</a>")
+                    appendln("</td>")
+                    appendln("<td>")
+                    append("${signatureGenerator.render(member)}")
+                    appendln("</td>")
+                    appendln("<td>")
+                    append("${member.doc.summary}")
+                    appendln("</td>")
+                    appendln("</tr>")
+                }
+                appendln("</tbody>")
+                appendln("</table>")
+
+            }
         }
     }
 }
\ No newline at end of file
diff --git a/src/Formats/MarkdownFormatService.kt b/src/Formats/MarkdownFormatService.kt
index 9626f62c..ae1500f2 100644
--- a/src/Formats/MarkdownFormatService.kt
+++ b/src/Formats/MarkdownFormatService.kt
@@ -1,45 +1,98 @@
 package org.jetbrains.dokka
 
 import org.jetbrains.dokka.DocumentationNode.Kind
+import java.util.LinkedHashMap
 
 public class MarkdownFormatService(val locationService: LocationService,
                                    val signatureGenerator: SignatureGenerator) : FormatService {
     override val extension: String = "md"
-    override fun format(node: DocumentationNode, to: StringBuilder) {
+    override fun format(nodes: Iterable<DocumentationNode>, to: StringBuilder) {
         with (to) {
-            appendln(node.path.map { "[${it.name}](${locationService.relativeLocation(node, it, extension)})" }.joinToString(" / "))
-            appendln()
-            appendln("# ${node.name}")
-            appendln(node.doc.summary)
-            appendln("```")
-            appendln(signatureGenerator.render(node))
-            appendln("```")
-            appendln(node.doc.description)
-            appendln()
-            for (section in node.doc.sections) {
-                append("##### ")
-                append(section.label)
-                appendln()
-                append(section.text)
+            val breakdown = nodes.groupByTo(LinkedHashMap()) { node ->
+                node.path.map { "[${it.name}](${locationService.relativeLocation(node, it, extension)})" }.joinToString(" / ")
+            }
+            for ((path, items) in breakdown) {
+                appendln(path)
                 appendln()
+                formatLocation(items)
             }
 
-            if (node.members.any()) {
-                appendln("### Members")
-                appendln("| Name | Signature | Summary |")
-                appendln("|------|-----------|---------|")
-                for (member in node.members.sortBy { it.name }) {
-                    val relativePath = locationService.relativeLocation(node, member, extension)
-                    val displayName = when (member.kind) {
-                        Kind.Constructor -> "*.init*"
-                        else -> signatureGenerator.renderName(member).htmlEscape()
+            for (node in nodes) {
+                if (node.members.any()) {
+                    appendln("## Members")
+                    appendln("| Name | Summary |")
+                    appendln("|------|---------|")
+                    val children = node.members.sortBy { it.name }
+                    val membersMap = children.groupByTo(LinkedHashMap()) { locationService.relativeLocation(node, it, extension) }
+                    for ((location, members) in membersMap) {
+                        val mainMember = members.first()
+                        val displayName = when (mainMember.kind) {
+                            Kind.Constructor -> "*.init*"
+                            else -> signatureGenerator.renderName(mainMember).htmlEscape()
+                        }
+                        append("|[${displayName}](${location})|")
+                        append(members.groupByTo(LinkedHashMap()) { it.doc.summary }.map { group ->
+                            val (summary, items) = group
+                            StringBuilder {
+                                if (!summary.isEmpty()) {
+                                    append("${summary}<br>")
+                                }
+                                for (item in items) {
+                                    append("&nbsp;&nbsp;`${signatureGenerator.render(item)}`<br>")
+                                }
+                            }.toString()
+                        }.joinToString("<br>"))
+                        appendln("|")
                     }
-                    append("|[${displayName}](${relativePath})")
-                    append("|`${signatureGenerator.render(member)}`")
-                    append("|${member.doc.summary} ")
-                    appendln("|")
+                }
+
+            }
+        }
+    }
+
+
+    private fun StringBuilder.formatLocation(nodes: Iterable<DocumentationNode>) {
+        val breakdown = nodes.groupByTo(LinkedHashMap()) { node ->
+            node.name
+        }
+        for ((name, items) in breakdown) {
+            appendln("# ${name}")
+            formatSummary(items)
+        }
+    }
+
+    private fun StringBuilder.formatSummary(nodes: Iterable<DocumentationNode>) {
+        val breakdown = nodes.groupByTo(LinkedHashMap()) { node ->
+            node.doc.summary
+        }
+        for ((summary, items) in breakdown) {
+            appendln(summary)
+            appendln("```")
+            for (item in items)
+                appendln(signatureGenerator.render(item))
+            appendln("```")
+        }
+
+        val described = nodes.filter { it.doc.hasDescription }
+        if (described.any()) {
+            appendln("## Description")
+            for (node in described) {
+                appendln("```")
+                appendln(signatureGenerator.render(node))
+                appendln("```")
+                appendln(node.doc.description)
+                appendln()
+                for (section in node.doc.sections) {
+                    append("**")
+                    append(section.label)
+                    append("**")
+                    appendln()
+                    append(section.text)
+                    appendln()
+                    appendln()
                 }
             }
         }
     }
+
 }
diff --git a/src/Formats/TextFormatService.kt b/src/Formats/TextFormatService.kt
index 1da1c0d0..2fb2a0a3 100644
--- a/src/Formats/TextFormatService.kt
+++ b/src/Formats/TextFormatService.kt
@@ -2,17 +2,19 @@ package org.jetbrains.dokka
 
 public class TextFormatService(val signatureGenerator: SignatureGenerator) : FormatService {
     override val extension: String = "txt"
-    override fun format(node: DocumentationNode, to: StringBuilder) {
-        with (to) {
-            appendln(signatureGenerator.render(node))
-            appendln()
-            appendln(node.doc.summary)
-            for (n in node.doc.summary.indices)
-                append("=")
+    override fun format(nodes: Iterable<DocumentationNode>, to: StringBuilder) {
+        for (node in nodes) {
+            with (to) {
+                appendln(signatureGenerator.render(node))
+                appendln()
+                appendln(node.doc.summary)
+                for (n in node.doc.summary.indices)
+                    append("=")
 
-            for (section in node.doc.sections) {
-                appendln(section.label)
-                appendln(section.text)
+                for (section in node.doc.sections) {
+                    appendln(section.label)
+                    appendln(section.text)
+                }
             }
         }
     }
-- 
cgit