don't generate "Description" header if nothing is going to follow it

5 files changed, 67 insertions, 6 deletions

diff --git a/src/Formats/StructuredFormatService.kt b/src/Formats/StructuredFormatService.kt
index 08b7e55d..adfac99c 100644
--- a/src/Formats/StructuredFormatService.kt
+++ b/src/Formats/StructuredFormatService.kt
@@ -78,9 +78,9 @@ public abstract class StructuredFormatService(val locationService: LocationServi
     }
 
     fun appendDescription(location: Location, to: StringBuilder, nodes: Iterable<DocumentationNode>) {
-        val described = nodes.filter { !it.content.isEmpty }
+        val described = nodes.filter { it.hasDescription() }
         if (described.any()) {
-            val single = described.size == 1
+            val single = described.size() == 1
             appendHeader(to, "Description", 3)
             for (node in described) {
                 if (!single) {
@@ -89,10 +89,7 @@ public abstract class StructuredFormatService(val locationService: LocationServi
                 appendLine(to, formatText(location, node.content.description))
                 appendLine(to)
                 for ((label, section) in node.content.sections) {
-                    if (label.startsWith("$"))
-                        continue
-                    if (node.members.any { it.name == label })
-                        continue
+                    if (!isDescriptionSection(label, node)) continue
                     appendLine(to, formatStrong(formatText(label)))
                     appendLine(to, formatText(location, section))
                 }
@@ -100,6 +97,17 @@ public abstract class StructuredFormatService(val locationService: LocationServi
         }
     }
 
+    private fun DocumentationNode.hasDescription() =
+       content.description != ContentEmpty || content.sections.any { isDescriptionSection(it.key, this) }
+
+    private fun isDescriptionSection(label: String, node: DocumentationNode): Boolean {
+        if (label.startsWith("$"))
+            return false
+        if (node.members.any { it.name == label })
+            return false
+        return true
+    }
+
     fun appendSummary(location: Location, to: StringBuilder, nodes: Iterable<DocumentationNode>) {
         val breakdownBySummary = nodes.groupByTo(LinkedHashMap()) { node ->
             formatText(location, node.summary)
diff --git a/test/data/format/emptyDescription.kt b/test/data/format/emptyDescription.kt
new file mode 100644
index 00000000..3ed81dfa
--- /dev/null
+++ b/test/data/format/emptyDescription.kt
@@ -0,0 +1,5 @@
+/**
+ * Function fn
+ */
+fun fn() {
+}
\ No newline at end of file
diff --git a/test/data/format/emptyDescription.md b/test/data/format/emptyDescription.md
new file mode 100644
index 00000000..5e8c05c0
--- /dev/null
+++ b/test/data/format/emptyDescription.md
@@ -0,0 +1,15 @@
+[test](out.md) / [](out.md) / [fn](out.md)
+
+
+# fn
+
+
+```
+fun fn(): Unit
+```
+
+
+Function fn
+
+
+
diff --git a/test/src/TestAPI.kt b/test/src/TestAPI.kt
index 5a4b9863..a16a0b57 100644
--- a/test/src/TestAPI.kt
+++ b/test/src/TestAPI.kt
@@ -5,6 +5,8 @@ import com.intellij.openapi.util.*
 import kotlin.test.fail
 import org.jetbrains.dokka.*
 import org.jetbrains.jet.lang.descriptors.DeclarationDescriptor
+import java.io.File
+import kotlin.test.assertEquals
 
 public fun verifyModel(vararg files: String, verifier: (DocumentationModule) -> Unit) {
     val messageCollector = object : MessageCollector {
@@ -49,6 +51,15 @@ public fun verifyModel(vararg files: String, verifier: (DocumentationModule) ->
     Disposer.dispose(environment)
 }
 
+public fun verifyOutput(path: String, outputGenerator: (DocumentationModule, StringBuilder) -> Unit) {
+    verifyModel(path) {
+        val output = StringBuilder()
+        outputGenerator(it, output)
+        val expectedOutput = File(path.replace(".kt", ".md")).readText()
+        assertEquals(expectedOutput, output.toString())
+    }
+}
+
 fun StringBuilder.appendChildren(node: ContentNode): StringBuilder {
     for (child in node.children) {
         val childText = child.toTestString()
@@ -83,3 +94,9 @@ fun ContentNode.toTestString(): String {
         appendNode(node)
     }.toString()
 }
+
+val tempLocation = Location(File("/tmp/out"))
+
+object InMemoryLocationService: LocationService {
+    override fun location(node: DocumentationNode) = tempLocation;
+}
diff --git a/test/src/format/MarkdownFormatTest.kt b/test/src/format/MarkdownFormatTest.kt
new file mode 100644
index 00000000..beb727da
--- /dev/null
+++ b/test/src/format/MarkdownFormatTest.kt
@@ -0,0 +1,16 @@
+package org.jetbrains.dokka.tests
+
+import org.junit.Test
+import org.jetbrains.dokka.*
+import java.io.File
+import kotlin.test.assertEquals
+
+public class MarkdownFormatTest {
+    private val markdownService = MarkdownFormatService(InMemoryLocationService, KotlinLanguageService())
+
+    Test fun emptyDescription() {
+        verifyOutput("test/data/format/emptyDescription.kt") { model, output ->
+            markdownService.appendNodes(tempLocation, output, model.members.single().members)
+        }
+    }
+}