From aeb2014eee704be377c06205d16f60562d2a8cf1 Mon Sep 17 00:00:00 2001
From: Błażej Kardyś <bkardys@virtuslab.com>
Date: Fri, 17 Jul 2020 03:48:03 +0200
Subject: Fixing javadoc comment parser for psi files

---
 .../jetbrains/dokka/javadoc/JavadocPageCreator.kt  | 21 ++++---
 .../javadoc/location/JavadocLocationProvider.kt    |  5 +-
 .../dokka/javadoc/pages/JavadocPageNodes.kt        |  1 +
 .../renderer/JavadocContentToHtmlTranslator.kt     | 65 +++++++++++++++-------
 .../JavadocContentToTemplateMapTranslator.kt       | 13 ++---
 .../dokka/javadoc/renderer/KorteJavadocRenderer.kt |  2 +-
 .../javadoc/src/main/resources/views/class.korte   |  2 +-
 7 files changed, 70 insertions(+), 39 deletions(-)

(limited to 'plugins/javadoc/src/main')

diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt
index 8b86fab0..b3bb49d3 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt
@@ -66,7 +66,8 @@ open class JavadocPageCreator(
                     )
                 },
                 documentable = c,
-                extra = ((c as? WithExtraProperties<Documentable>)?.extra ?: PropertyContainer.empty()) + c.indexesInDocumentation()
+                extra = ((c as? WithExtraProperties<Documentable>)?.extra
+                    ?: PropertyContainer.empty()) + c.indexesInDocumentation()
             )
         }
 
@@ -142,6 +143,7 @@ open class JavadocPageCreator(
             dri = dri,
             signature = signatureForNode(this, jvm),
             brief = brief(jvm),
+            description = descriptionToContentNodes(jvm),
             parameters = parameters.mapNotNull {
                 val signature = signatureForNode(it, jvm)
                 signature.modifiers?.let { type ->
@@ -194,16 +196,21 @@ open class JavadocPageCreator(
         briefFromContentNodes(descriptionToContentNodes(sourceSet))
 
     private fun briefFromContentNodes(description: List<ContentNode>): List<ContentNode> {
-        val contents = mutableListOf<ContentNode>()
-        for (node in description) {
+        var sentenceFound = false
+        fun lookthrough(node: ContentNode): ContentNode =
             if (node is ContentText && firstSentenceRegex.containsMatchIn(node.text)) {
-                contents.add(node.copy(text = firstSentenceRegex.find(node.text)?.value.orEmpty()))
-                break
+                sentenceFound = true
+                node.copy(text = firstSentenceRegex.find(node.text)?.value.orEmpty())
+            } else if (node is ContentGroup) {
+                node.copy(children = node.children.mapNotNull {
+                    if (!sentenceFound) lookthrough(it) else null
+                }, style = node.style - TextStyle.Paragraph)
             } else {
-                contents.add(node)
+                node
             }
+        return description.mapNotNull {
+            if (!sentenceFound) lookthrough(it) else null
         }
-        return contents
     }
 
     private fun DParameter.brief(sourceSet: DokkaSourceSet? = highestJvmSourceSet): List<ContentNode> =
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/location/JavadocLocationProvider.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/location/JavadocLocationProvider.kt
index 7f27ff18..e0a7768c 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/location/JavadocLocationProvider.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/location/JavadocLocationProvider.kt
@@ -66,7 +66,7 @@ class JavadocLocationProvider(pageRoot: RootPageNode, dokkaContext: DokkaContext
 
     override fun resolve(dri: DRI, sourceSets: Set<DokkaSourceSet>, context: PageNode?): String {
         return nodeIndex[dri]?.let { resolve(it, context) }
-            ?: nodeIndex[dri.parent]?.let {
+            ?: nodeIndex[dri.parent]?.takeIf { it is JavadocClasslikePageNode }?.let {
                 val anchor = when (val anchorElement = (it as? JavadocClasslikePageNode)?.findAnchorableByDRI(dri)) {
                     is JavadocFunctionNode -> anchorElement.getAnchor()
                     is JavadocEntryNode -> anchorElement.name
@@ -80,7 +80,8 @@ class JavadocLocationProvider(pageRoot: RootPageNode, dokkaContext: DokkaContext
 
     private fun JavadocFunctionNode.getAnchor(): String =
         "$name(${parameters.joinToString(",") {
-            when (val bound = if (it.typeBound is org.jetbrains.dokka.model.Nullable) it.typeBound.inner else it.typeBound) {
+            when (val bound =
+                if (it.typeBound is org.jetbrains.dokka.model.Nullable) it.typeBound.inner else it.typeBound) {
                 is TypeConstructor -> bound.dri.classNames.orEmpty()
                 is OtherParameter -> bound.name
                 is PrimitiveJavaType -> bound.name
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt
index 790e15c5..ec4591c3 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt
@@ -115,6 +115,7 @@ data class JavadocPropertyNode(
 data class JavadocFunctionNode(
     val signature: JavadocSignatureContentNode,
     val brief: List<ContentNode>,
+    val description: List<ContentNode>,
     val parameters: List<JavadocParameterNode>,
     val name: String,
     override val dri: DRI,
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToHtmlTranslator.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToHtmlTranslator.kt
index 906c9d5a..1e9a3d65 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToHtmlTranslator.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToHtmlTranslator.kt
@@ -14,37 +14,51 @@ internal class JavadocContentToHtmlTranslator(
 
     fun htmlForContentNode(node: ContentNode, relative: PageNode?): String =
         when (node) {
-            is ContentGroup -> htmlForContentNodes(node.children, node.style, relative)
-            is ContentText -> buildText(node)
-            is ContentDRILink -> buildLink(
-                locationProvider.resolve(node.address, node.sourceSets, relative),
-                htmlForContentNodes(node.children, node.style, relative)
-            )
-            is ContentResolvedLink -> buildLink(node.address, htmlForContentNodes(node.children, node.style, relative))
-            is ContentCode -> htmlForCode(node.children)
+            is ContentGroup ->
+                if (node.style.contains(TextStyle.Paragraph)) htmlForParagraph(node.children, relative)
+                else htmlForContentNodes(node.children, relative)
+            is ContentText -> htmlForText(node)
+            is ContentDRILink -> buildLinkFromNode(node, relative)
+            is ContentResolvedLink -> buildLinkFromNode(node, relative)
+            is ContentCode -> htmlForCode(node.children, relative)
+            is ContentList -> htmlForList(node.children, relative)
             is JavadocSignatureContentNode -> htmlForSignature(node, relative)
+            is ContentBreakLine -> "<br>"
             else -> ""
         }
 
-    fun htmlForContentNodes(list: List<ContentNode>, styles: Set<Style>, relative: PageNode?) =
-        list.joinToString(separator = "") { htmlForContentNode(it, relative) }
-
-    private fun buildText(node: ContentText): String {
+    fun htmlForText(node: ContentText): String {
         val escapedText = node.text.htmlEscape()
-        return if (node.style.contains(ContentStyle.InDocumentationAnchor)) {
-            """<em><a id="$escapedText" class="searchTagResult">${escapedText}</a></em>"""
-        } else {
-            escapedText
+        return when {
+            node.style.contains(ContentStyle.InDocumentationAnchor) -> """<em><a id="$escapedText" class="searchTagResult">${escapedText}</a></em>"""
+            node.style.contains(TextStyle.Bold) -> "<b>$escapedText</b>"
+            node.style.contains(TextStyle.Italic) -> "<i>$escapedText</i>"
+            node.style.contains(TextStyle.Strikethrough) -> "<del>$escapedText</del>"
+            else -> node.text.htmlEscape()
         }
     }
 
-    private fun htmlForCode(code: List<ContentNode>): String = code.map { element ->
-        when (element) {
-            is ContentText -> element.text
+    fun htmlForContentNodes(list: List<ContentNode>, relative: PageNode?) =
+        list.joinToString(separator = "") { htmlForContentNode(it, relative) }
+
+    private fun htmlForParagraph(nodes: List<ContentNode>, relative: PageNode?) =
+        "<p>${htmlForContentNodes(nodes, relative)}</p>"
+
+    private fun htmlForCode(code: List<ContentNode>, relative: PageNode?): String {
+        fun nodeToText(node: ContentNode): String = when (node) {
+            is ContentText -> node.text
             is ContentBreakLine -> ""
-            else -> run { context.logger.error("Cannot cast $element as ContentText!"); "" }
+            is ContentDRILink -> buildLinkFromNode(node, relative)
+            is ContentResolvedLink -> buildLinkFromNode(node, relative)
+            is ContentCode -> node.children.joinToString("") { nodeToText(it) }
+            else -> run { context.logger.error("Cannot cast $node as ContentText!"); "" }
         }
-    }.joinToString("<br>", """<span class="code">""", "</span>") { it }
+        return code.map(::nodeToText).joinToString("<br>", """<code>""", "</code>") { it }
+    }
+
+    private fun htmlForList(elements: List<ContentNode>, relative: PageNode?) =
+        elements.filterIsInstance<ContentGroup>()
+            .joinToString("", "<ul>", "</ul>") { "<li>${htmlForContentNode(it, relative)}</li>" }
 
     private fun htmlForSignature(node: JavadocSignatureContentNode, relative: PageNode?): String =
         listOfNotNull(
@@ -54,6 +68,15 @@ internal class JavadocContentToHtmlTranslator(
             node.supertypes
         ).joinToString(separator = " ") { htmlForContentNode(it, relative) }
 
+    private fun buildLinkFromNode(node: ContentDRILink, relative: PageNode?) =
+        buildLink(
+            locationProvider.resolve(node.address, node.sourceSets, relative),
+            htmlForContentNodes(node.children, relative)
+        )
+
+    private fun buildLinkFromNode(node: ContentResolvedLink, relative: PageNode?) =
+        buildLink(node.address, htmlForContentNodes(node.children, relative))
+
     companion object {
 
         fun buildLink(address: String, content: String) =
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt
index 1a286095..57255cf1 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt
@@ -72,22 +72,21 @@ internal class JavadocContentToTemplateMapTranslator(
             )
         }
 
-        fun templateMapForPackagePageNode(node: JavadocPackagePageNode): TemplateMap {
-            return mapOf(
+        fun templateMapForPackagePageNode(node: JavadocPackagePageNode): TemplateMap =
+            mapOf(
                 "kind" to "package"
             ) + templateMapForJavadocContentNode(node.content)
-        }
 
-        fun templateMapForFunctionNode(node: JavadocFunctionNode): TemplateMap {
-            return mapOf(
+        fun templateMapForFunctionNode(node: JavadocFunctionNode): TemplateMap =
+            mapOf(
                 "brief" to htmlForContentNodes(node.brief, contextNode),
+                "description" to htmlForContentNodes(node.description, contextNode),
                 "parameters" to node.parameters.map { templateMapForParameterNode(it) },
                 "inlineParameters" to node.parameters.joinToString { renderInlineParameter(it) },
                 "anchorLink" to locationProvider.anchorForFunctionNode(node),
                 "signature" to templateMapForSignatureNode(node.signature),
                 "name" to node.name
             )
-        }
 
         fun templateMapForClasslikeNode(node: JavadocClasslikePageNode): TemplateMap =
             mapOf(
@@ -214,7 +213,7 @@ internal class JavadocContentToTemplateMapTranslator(
             htmlTranslator.htmlForContentNode(node, relativeNode)
 
         private fun htmlForContentNodes(nodes: List<ContentNode>, relativeNode: PageNode) =
-            htmlTranslator.htmlForContentNodes(nodes, emptySet(), relativeNode)
+            htmlTranslator.htmlForContentNodes(nodes, relativeNode)
     }
 
     private fun DRI.displayable(): String = "${packageName}.${sureClassNames}"
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/KorteJavadocRenderer.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/KorteJavadocRenderer.kt
index 092fed2c..7826e590 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/KorteJavadocRenderer.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/KorteJavadocRenderer.kt
@@ -119,7 +119,7 @@ class KorteJavadocRenderer(private val outputWriter: OutputWriter, val context:
                 (buildLink(
                     locationProvider.resolve(link, contextRoot),
                     link.name
-                ) to contentToHtmlTranslator.htmlForContentNodes(doc, emptySet(), contextRoot)).pairToTag().trim()
+                ) to contentToHtmlTranslator.htmlForContentNodes(doc, contextRoot)).pairToTag().trim()
             },
             TeFunction("createListRow") { args ->
                 val link = args.first() as LinkJavadocListEntry
diff --git a/plugins/javadoc/src/main/resources/views/class.korte b/plugins/javadoc/src/main/resources/views/class.korte
index ddaadc3a..048a479e 100644
--- a/plugins/javadoc/src/main/resources/views/class.korte
+++ b/plugins/javadoc/src/main/resources/views/class.korte
@@ -270,7 +270,7 @@
                                     <li class="blockList">
                                         <h4>{{ method.name }}</h4>
                                         <pre class="methodSignature">{{ method.signature.annotations|raw }} {{ method.signature.modifiers|raw }} {{ method.signature.signatureWithoutModifiers|raw}}</pre>
-                                        <div class="block">{{ method.brief|raw }}</div>
+                                        <div class="block">{{ method.description|raw }}</div>
                                         {% if method.parameters.size != 0 && hasAnyDescription(method.parameters) %}
                                         <dl>
                                             <dt><span class="paramLabel">Parameters:</span></dt>
-- 
cgit