Fix rendering html in briefs (#1931)

6 files changed, 159 insertions, 51 deletions

diff --git a/plugins/base/src/main/kotlin/translators/documentables/briefFromContentNodes.kt b/plugins/base/src/main/kotlin/translators/documentables/briefFromContentNodes.kt
index ca66c1a8..7ac6763d 100644
--- a/plugins/base/src/main/kotlin/translators/documentables/briefFromContentNodes.kt
+++ b/plugins/base/src/main/kotlin/translators/documentables/briefFromContentNodes.kt
@@ -1,16 +1,20 @@
 package org.jetbrains.dokka.base.translators.documentables
 
-import org.jetbrains.dokka.pages.ContentGroup
-import org.jetbrains.dokka.pages.ContentNode
-import org.jetbrains.dokka.pages.ContentText
-import org.jetbrains.dokka.pages.TextStyle
+import org.jetbrains.dokka.model.withDescendants
+import org.jetbrains.dokka.pages.*
+import org.jetbrains.kotlin.utils.addToStdlib.safeAs
 
 fun briefFromContentNodes(description: List<ContentNode>): List<ContentNode> {
     val firstSentenceRegex = """^((?:[^.?!]|[.!?](?!\s))*[.!?])""".toRegex()
 
+    //Description that is entirely based on html content. In html it is hard to define a brief so we render all of it
+    if(description.all { it.withDescendants().all { it is ContentGroup || it.safeAs<ContentText>()?.isHtml == true } }){
+        return description
+    }
+
     var sentenceFound = false
     fun lookthrough(node: ContentNode): ContentNode =
-        if (node is ContentText && firstSentenceRegex.containsMatchIn(node.text)) {
+        if (node is ContentText && !node.isHtml && firstSentenceRegex.containsMatchIn(node.text)) {
             sentenceFound = true
             node.copy(text = firstSentenceRegex.find(node.text)?.value.orEmpty())
         } else if (node is ContentGroup) {
@@ -24,3 +28,6 @@ fun briefFromContentNodes(description: List<ContentNode>): List<ContentNode> {
         if (!sentenceFound) lookthrough(it) else null
     }
 }
+
+private val ContentText.isHtml
+    get() = extra[HtmlContent] != null
diff --git a/plugins/base/src/test/kotlin/multiplatform/BasicMultiplatformTest.kt b/plugins/base/src/test/kotlin/multiplatform/BasicMultiplatformTest.kt
index c8978d32..1a1340dc 100644
--- a/plugins/base/src/test/kotlin/multiplatform/BasicMultiplatformTest.kt
+++ b/plugins/base/src/test/kotlin/multiplatform/BasicMultiplatformTest.kt
@@ -20,7 +20,7 @@ class BasicMultiplatformTest : BaseAbstractTest() {
 
         testFromData(configuration) {
             pagesTransformationStage = {
-                assertEquals(6, it.children.firstOrNull()?.children?.count() ?: 0)
+                assertEquals(7, it.children.firstOrNull()?.children?.count() ?: 0)
             }
         }
     }
diff --git a/plugins/base/src/test/kotlin/signatures/AbstractRenderingTest.kt b/plugins/base/src/test/kotlin/signatures/AbstractRenderingTest.kt
new file mode 100644
index 00000000..5ea5c02c
--- /dev/null
+++ b/plugins/base/src/test/kotlin/signatures/AbstractRenderingTest.kt
@@ -0,0 +1,55 @@
+package signatures
+
+import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import org.jsoup.Jsoup
+import org.jsoup.nodes.Element
+import utils.TestOutputWriterPlugin
+import java.nio.file.Paths
+
+abstract class AbstractRenderingTest : BaseAbstractTest() {
+    val testDataDir = getTestDataDir("multiplatform/basicMultiplatformTest").toAbsolutePath()
+
+    val configuration = dokkaConfiguration {
+        moduleName = "example"
+        sourceSets {
+            val common = sourceSet {
+                name = "common"
+                displayName = "common"
+                analysisPlatform = "common"
+                sourceRoots = listOf(Paths.get("$testDataDir/commonMain/kotlin").toString())
+            }
+            val jvmAndJsSecondCommonMain = sourceSet {
+                name = "jvmAndJsSecondCommonMain"
+                displayName = "jvmAndJsSecondCommonMain"
+                analysisPlatform = "common"
+                dependentSourceSets = setOf(common.value.sourceSetID)
+                sourceRoots = listOf(Paths.get("$testDataDir/jvmAndJsSecondCommonMain/kotlin").toString())
+            }
+            val js = sourceSet {
+                name = "js"
+                displayName = "js"
+                analysisPlatform = "js"
+                dependentSourceSets = setOf(common.value.sourceSetID, jvmAndJsSecondCommonMain.value.sourceSetID)
+                sourceRoots = listOf(Paths.get("$testDataDir/jsMain/kotlin").toString())
+            }
+            val jvm = sourceSet {
+                name = "jvm"
+                displayName = "jvm"
+                analysisPlatform = "jvm"
+                dependentSourceSets = setOf(common.value.sourceSetID, jvmAndJsSecondCommonMain.value.sourceSetID)
+                sourceRoots = listOf(Paths.get("$testDataDir/jvmMain/kotlin").toString())
+            }
+        }
+    }
+
+    fun TestOutputWriterPlugin.renderedContent(path: String) = writer.contents.getValue(path)
+        .let { Jsoup.parse(it) }.select("#content").single()
+
+    fun TestOutputWriterPlugin.renderedDivergentContent(path: String) = renderedContent(path).select("div.divergent-group")
+
+    val Element.brief: String
+        get() = children().select("p").text()
+
+    val Element.rawBrief: String
+        get() = children().select("p").html()
+}
\ No newline at end of file
diff --git a/plugins/base/src/test/kotlin/signatures/DivergentSignatureTest.kt b/plugins/base/src/test/kotlin/signatures/DivergentSignatureTest.kt
index 0d40821b..6471f555 100644
--- a/plugins/base/src/test/kotlin/signatures/DivergentSignatureTest.kt
+++ b/plugins/base/src/test/kotlin/signatures/DivergentSignatureTest.kt
@@ -7,43 +7,9 @@ import org.jsoup.select.Elements
 import org.junit.jupiter.api.Test
 import java.nio.file.Paths
 import utils.TestOutputWriterPlugin
+import kotlin.test.assertEquals
 
-class DivergentSignatureTest : BaseAbstractTest() {
-
-    val testDataDir = getTestDataDir("multiplatform/basicMultiplatformTest").toAbsolutePath()
-
-    val configuration = dokkaConfiguration {
-        moduleName = "example"
-        sourceSets {
-            val common = sourceSet {
-                name = "common"
-                displayName = "common"
-                analysisPlatform = "common"
-                sourceRoots = listOf(Paths.get("$testDataDir/commonMain/kotlin").toString())
-            }
-            val jvmAndJsSecondCommonMain = sourceSet {
-                name = "jvmAndJsSecondCommonMain"
-                displayName = "jvmAndJsSecondCommonMain"
-                analysisPlatform = "common"
-                dependentSourceSets = setOf(common.value.sourceSetID)
-                sourceRoots = listOf(Paths.get("$testDataDir/jvmAndJsSecondCommonMain/kotlin").toString())
-            }
-            val js = sourceSet {
-                name = "js"
-                displayName = "js"
-                analysisPlatform = "js"
-                dependentSourceSets = setOf(common.value.sourceSetID, jvmAndJsSecondCommonMain.value.sourceSetID)
-                sourceRoots = listOf(Paths.get("$testDataDir/jsMain/kotlin").toString())
-            }
-            val jvm = sourceSet {
-                name = "jvm"
-                displayName = "jvm"
-                analysisPlatform = "jvm"
-                dependentSourceSets = setOf(common.value.sourceSetID, jvmAndJsSecondCommonMain.value.sourceSetID)
-                sourceRoots = listOf(Paths.get("$testDataDir/jvmMain/kotlin").toString())
-            }
-        }
-    }
+class DivergentSignatureTest : AbstractRenderingTest() {
 
     @Test
     fun `group { common + jvm + js }`() {
@@ -55,7 +21,7 @@ class DivergentSignatureTest : BaseAbstractTest() {
             pluginOverrides = listOf(writerPlugin)
         ) {
             renderingStage = { _, _ ->
-                val content = writerPlugin.renderedContent("example/example/-clock/get-time.html")
+                val content = writerPlugin.renderedDivergentContent("example/example/-clock/get-time.html")
 
                 assert(content.count() == 1)
                 assert(content.select("[data-filterable-current=example/common example/js example/jvm]").single().brief == "")
@@ -73,7 +39,7 @@ class DivergentSignatureTest : BaseAbstractTest() {
             pluginOverrides = listOf(writerPlugin)
         ) {
             renderingStage = { _, _ ->
-                val content = writerPlugin.renderedContent("example/example/-clock/get-times-in-millis.html")
+                val content = writerPlugin.renderedDivergentContent("example/example/-clock/get-times-in-millis.html")
                 assert(content.count() == 2)
                 assert(content.select("[data-filterable-current=example/common example/jvm]").single().brief == "Time in minis")
                 assert(content.select("[data-filterable-current=example/js]").single().brief == "JS implementation of getTimeInMillis" )
@@ -91,7 +57,7 @@ class DivergentSignatureTest : BaseAbstractTest() {
             pluginOverrides = listOf(writerPlugin)
         ) {
             renderingStage = { _, _ ->
-                val content = writerPlugin.renderedContent("example/example/-clock/get-year.html")
+                val content = writerPlugin.renderedDivergentContent("example/example/-clock/get-year.html")
                 assert(content.count() == 3)
                 assert(content.select("[data-filterable-current=example/jvm]").single().brief == "JVM custom kdoc")
                 assert(content.select("[data-filterable-current=example/js]").single().brief == "JS custom kdoc")
@@ -99,10 +65,4 @@ class DivergentSignatureTest : BaseAbstractTest() {
             }
         }
     }
-
-    private fun TestOutputWriterPlugin.renderedContent(path: String) = writer.contents.getValue(path)
-            .let { Jsoup.parse(it) }.select("#content").single().select("div.divergent-group")
-
-    private val Element.brief: String
-        get() = children().select("p").text()
 }
diff --git a/plugins/base/src/test/kotlin/signatures/RawHtmlRenderingTest.kt b/plugins/base/src/test/kotlin/signatures/RawHtmlRenderingTest.kt
new file mode 100644
index 00000000..c741ac8b
--- /dev/null
+++ b/plugins/base/src/test/kotlin/signatures/RawHtmlRenderingTest.kt
@@ -0,0 +1,66 @@
+package signatures
+
+import org.jsoup.Jsoup
+import org.junit.jupiter.api.Test
+import utils.TestOutputWriterPlugin
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class RawHtmlRenderingTest: AbstractRenderingTest() {
+    @Test
+    fun `work with raw html with inline comment`() {
+        val writerPlugin = TestOutputWriterPlugin()
+
+        testFromData(
+            configuration,
+            pluginOverrides = listOf(writerPlugin)
+        ) {
+            renderingStage = { _, _ ->
+                val content = writerPlugin.renderedDivergentContent("example/example/-html-test/test.html")
+                assert(content.count() == 1)
+                assertEquals(content.select("[data-filterable-current=example/jvm]").single().rawBrief,"This is an example <!-- not visible --> of html")
+
+                val indexContent = writerPlugin.writer.contents.getValue("example/example/-html-test/index.html")
+                    .let { Jsoup.parse(it) }
+                assertTrue(indexContent.select("div.brief").any { it.html().contains("This is an example <!-- not visible --> of html")})
+            }
+        }
+    }
+
+    @Test
+    fun `work with raw html`() {
+        val writerPlugin = TestOutputWriterPlugin()
+
+        testFromData(
+            configuration,
+            pluginOverrides = listOf(writerPlugin)
+        ) {
+            renderingStage = { _, _ ->
+                //Module page
+                val content = writerPlugin.renderedContent("example/example/index.html").select("div.brief")
+                assertTrue(content.size > 0)
+                assertTrue(content.any { it.html().contains("<!-- this shouldn't be visible -->")})
+            }
+        }
+    }
+
+    @Test
+    fun `work with raw, visible html`() {
+        val writerPlugin = TestOutputWriterPlugin()
+
+        testFromData(
+            configuration,
+            pluginOverrides = listOf(writerPlugin)
+        ) {
+            renderingStage = { _, _ ->
+                val content = writerPlugin.renderedDivergentContent("example/example/-html-test/test-p.html")
+                assert(content.count() == 1)
+                assertEquals(content.select("[data-filterable-current=example/jvm]").single().rawBrief, "This is an <b> documentation </b>")
+
+                val indexContent = writerPlugin.writer.contents.getValue("example/example/-html-test/index.html")
+                    .let { Jsoup.parse(it) }
+                assertTrue(indexContent.select("div.brief").any { it.html().contains("This is an <b> documentation </b>")})
+            }
+        }
+    }
+}
\ No newline at end of file
diff --git a/plugins/base/src/test/resources/multiplatform/basicMultiplatformTest/jvmMain/kotlin/example/HtmlTest.kt b/plugins/base/src/test/resources/multiplatform/basicMultiplatformTest/jvmMain/kotlin/example/HtmlTest.kt
new file mode 100644
index 00000000..9e6fef4a
--- /dev/null
+++ b/plugins/base/src/test/resources/multiplatform/basicMultiplatformTest/jvmMain/kotlin/example/HtmlTest.kt
@@ -0,0 +1,20 @@
+package example
+
+/**
+ * <!-- this shouldn't be visible -->
+ */
+class HtmlTest {
+    /**
+     * This is an example <!-- not visible --> of html
+     */
+    fun test(){
+
+    }
+
+    /**
+     * This is an <b> documentation </b>
+     */
+    fun testP(){
+
+    }
+}
\ No newline at end of file