Handle html in kdoc (#1805)

5 files changed, 63 insertions, 4 deletions

diff --git a/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt b/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt
index 37b1db47..2e7eb24b 100644
--- a/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt
+++ b/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt
@@ -1,7 +1,6 @@
 package org.jetbrains.dokka.base.parsers
 
 import com.intellij.psi.PsiElement
-import org.intellij.markdown.MarkdownElementType
 import org.intellij.markdown.MarkdownElementTypes
 import org.intellij.markdown.MarkdownTokenTypes
 import org.intellij.markdown.ast.ASTNode
@@ -288,6 +287,13 @@ open class MarkdownParser(
             )
         }
 
+
+    private fun rawHtmlHandler(node: ASTNode): DocTag =
+        DocTagsFromIElementFactory.getInstance(
+            node.type,
+            body = text.substring(node.startOffset, node.endOffset)
+        )
+
     private fun codeSpansHandler(node: ASTNode) =
         DocTagsFromIElementFactory.getInstance(
             node.type,
@@ -356,6 +362,9 @@ open class MarkdownParser(
             MarkdownElementTypes.CODE_FENCE -> codeFencesHandler(node)
             MarkdownElementTypes.CODE_SPAN -> codeSpansHandler(node)
             MarkdownElementTypes.IMAGE -> imagesHandler(node)
+            MarkdownElementTypes.HTML_BLOCK,
+            MarkdownTokenTypes.HTML_TAG,
+            MarkdownTokenTypes.HTML_BLOCK_CONTENT -> rawHtmlHandler(node)
             MarkdownTokenTypes.HARD_LINE_BREAK -> DocTagsFromIElementFactory.getInstance(node.type)
             MarkdownTokenTypes.CODE_FENCE_CONTENT,
             MarkdownTokenTypes.CODE_LINE -> codeLineHandler(node)
@@ -400,7 +409,12 @@ open class MarkdownParser(
         if (index == lastIndex && elemTransformed is Text) elemTransformed.copy(elemTransformed.body.trimEnd()) else elemTransformed
     }
 
-    private val notLeafNodes = listOf(MarkdownTokenTypes.HORIZONTAL_RULE, MarkdownTokenTypes.HARD_LINE_BREAK)
+    private val notLeafNodes = listOf(
+        MarkdownTokenTypes.HORIZONTAL_RULE,
+        MarkdownTokenTypes.HARD_LINE_BREAK,
+        MarkdownTokenTypes.HTML_TAG,
+        MarkdownTokenTypes.HTML_BLOCK_CONTENT
+    )
 
     private fun List<ASTNode>.isNotLeaf(index: Int): Boolean =
         if (index in 0..this.lastIndex)
diff --git a/plugins/base/src/main/kotlin/parsers/factories/DocTagsFromIElementFactory.kt b/plugins/base/src/main/kotlin/parsers/factories/DocTagsFromIElementFactory.kt
index b714caec..9ee11732 100644
--- a/plugins/base/src/main/kotlin/parsers/factories/DocTagsFromIElementFactory.kt
+++ b/plugins/base/src/main/kotlin/parsers/factories/DocTagsFromIElementFactory.kt
@@ -7,6 +7,7 @@ import org.intellij.markdown.MarkdownTokenTypes
 import org.intellij.markdown.flavours.gfm.GFMElementTypes
 import org.intellij.markdown.flavours.gfm.GFMTokenTypes
 import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.doc.DocTag.Companion.contentTypeParam
 import java.lang.NullPointerException
 
 object DocTagsFromIElementFactory {
@@ -41,6 +42,9 @@ object DocTagsFromIElementFactory {
             GFMElementTypes.ROW                         -> Tr(children, params)
             GFMTokenTypes.CELL                          -> Td(children, params)
             MarkdownElementTypes.MARKDOWN_FILE          -> CustomDocTag(children, params, MarkdownElementTypes.MARKDOWN_FILE.name)
+            MarkdownElementTypes.HTML_BLOCK,
+            MarkdownTokenTypes.HTML_TAG,
+            MarkdownTokenTypes.HTML_BLOCK_CONTENT       -> Text(body.orEmpty(), params = params + contentTypeParam("html"))
             else                                        -> CustomDocTag(children, params, type.name)
         }
 }
diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
index f0d86b97..6d6f71fb 100644
--- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
@@ -22,6 +22,7 @@ import org.jetbrains.dokka.model.properties.PropertyContainer
 import org.jetbrains.dokka.model.sourceSetIDs
 import org.jetbrains.dokka.model.withDescendants
 import org.jetbrains.dokka.pages.*
+import org.jetbrains.dokka.pages.HtmlContent
 import org.jetbrains.dokka.plugability.*
 import org.jetbrains.dokka.utilities.htmlEscape
 import java.net.URI
@@ -704,6 +705,9 @@ open class HtmlRenderer(
 
     override fun FlowContent.buildText(textNode: ContentText) =
         when {
+            textNode.extra[HtmlContent] != null -> {
+                consumer.onTagContentUnsafe { raw(textNode.text) }
+            }
             textNode.hasStyle(TextStyle.Indented) -> {
                 consumer.onTagContentEntity(Entities.nbsp)
                 text(textNode.text)
diff --git a/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt b/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt
index a3a9ad6a..a02f1b53 100644
--- a/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt
+++ b/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt
@@ -7,6 +7,7 @@ import org.jetbrains.dokka.model.properties.PropertyContainer
 import org.jetbrains.dokka.model.toDisplaySourceSets
 import org.jetbrains.dokka.pages.*
 import org.jetbrains.kotlin.utils.addToStdlib.firstIsInstanceOrNull
+import org.jetbrains.dokka.model.properties.plus
 
 open class DocTagToContentConverter : CommentsToContentConverter {
     override fun buildContent(
@@ -145,7 +146,8 @@ open class DocTagToContentConverter : CommentsToContentConverter {
                     docTag.body,
                     dci,
                     sourceSets.toDisplaySourceSets(),
-                    styles
+                    styles,
+                    extra + HtmlContent.takeIf { docTag.params["content-type"] == "html" }
                 )
             )
             is Strikethrough -> buildChildren(docTag, setOf(TextStyle.Strikethrough))
@@ -204,7 +206,6 @@ open class DocTagToContentConverter : CommentsToContentConverter {
                     styles
                 )
             )
-
             is CustomDocTag -> if (docTag.isNonemptyFile()) {
                 listOf(
                     ContentGroup(
diff --git a/plugins/base/src/test/kotlin/markdown/ParserTest.kt b/plugins/base/src/test/kotlin/markdown/ParserTest.kt
index 4ac4a43f..a9e1eee4 100644
--- a/plugins/base/src/test/kotlin/markdown/ParserTest.kt
+++ b/plugins/base/src/test/kotlin/markdown/ParserTest.kt
@@ -1481,5 +1481,41 @@ class ParserTest : KDocTest() {
             exception?.message
         )
     }
+
+    @Test
+    fun `should ignore html comments`() {
+        val kdoc = """
+        | # Example <!--- not visible in header --> Kdoc
+        | <!-- not visible alone -->
+        | Pre <!--- not visible --> visible
+        """.trimMargin()
+        val expectedDocumentationNode = DocumentationNode(
+            listOf(
+                Description(
+                    CustomDocTag(
+                        listOf(
+                            H1(
+                                listOf(
+                                    Text("Example "),
+                                    Text("<!--- not visible in header -->", params = mapOf("content-type" to "html")),
+                                    Text(" Kdoc")
+                                )
+                            ),
+                            Text("<!-- not visible alone -->", params = mapOf("content-type" to "html")),
+                            P(
+                                listOf(
+                                    Text("Pre "),
+                                    Text("<!--- not visible -->", params = mapOf("content-type" to "html")),
+                                    Text(" visible")
+                                )
+                            )
+                        ),
+                        name = MarkdownElementTypes.MARKDOWN_FILE.name
+                    )
+                )
+            )
+        )
+        executeTest(kdoc, expectedDocumentationNode)
+    }
 }