Introduce top-level DocTag

Kotlin · Oct 7, 2020 · ec63795 · ec63795
1 parent 7c4301a
commit ec63795
Show file tree

Hide file tree

Showing 19 changed files with 439 additions and 286 deletions.
diff --git a/core/src/main/kotlin/model/doc/DocTag.kt b/core/src/main/kotlin/model/doc/DocTag.kt
@@ -51,7 +51,8 @@ data class CodeBlock(
 
 data class CustomDocTag(
     override val children: List<DocTag> = emptyList(),
-    override val params: Map<String, String> = emptyMap()
+    override val params: Map<String, String> = emptyMap(),
+    val name: String
 ) : DocTag()
 
 data class Dd(

diff --git a/core/src/main/kotlin/model/doc/TagWrapper.kt b/core/src/main/kotlin/model/doc/TagWrapper.kt
@@ -3,38 +3,28 @@ package org.jetbrains.dokka.model.doc
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.WithChildren
 
-sealed class TagWrapper(val root: DocTag) : WithChildren<DocTag> {
-
+sealed class TagWrapper : WithChildren<DocTag> {
+    abstract val root: DocTag
     override val children: List<DocTag>
         get() = root.children
-
-    override fun equals(other: Any?): Boolean =
-        (
-                other != null &&
-                        this::class == other::class &&
-                        this.root == (other as TagWrapper).root
-                )
-
-    override fun hashCode(): Int = root.hashCode()
 }
 
-sealed class NamedTagWrapper(root: DocTag, val name: String) : TagWrapper(root) {
-    override fun equals(other: Any?): Boolean = super.equals(other) && this.name == (other as NamedTagWrapper).name
-    override fun hashCode(): Int = super.hashCode() + name.hashCode()
+sealed class NamedTagWrapper : TagWrapper() {
+    abstract val name: String
 }
 
-class Description(root: DocTag) : TagWrapper(root)
-class Author(root: DocTag) : TagWrapper(root)
-class Version(root: DocTag) : TagWrapper(root)
-class Since(root: DocTag) : TagWrapper(root)
-class See(root: DocTag, name: String, val address: DRI?) : NamedTagWrapper(root, name)
-class Param(root: DocTag, name: String) : NamedTagWrapper(root, name)
-class Return(root: DocTag) : TagWrapper(root)
-class Receiver(root: DocTag) : TagWrapper(root)
-class Constructor(root: DocTag) : TagWrapper(root)
-class Throws(root: DocTag, name: String) : NamedTagWrapper(root, name)
-class Sample(root: DocTag, name: String) : NamedTagWrapper(root, name)
-class Deprecated(root: DocTag) : TagWrapper(root)
-class Property(root: DocTag, name: String) : NamedTagWrapper(root, name)
-class Suppress(root: DocTag) : TagWrapper(root)
-class CustomTagWrapper(root: DocTag, name: String) : NamedTagWrapper(root, name)
+data class Description(override val root: DocTag) : TagWrapper()
+data class Author(override val root: DocTag) : TagWrapper()
+data class Version(override val root: DocTag) : TagWrapper()
+data class Since(override val root: DocTag) : TagWrapper()
+data class See(override val root: DocTag, override val name: String, val address: DRI?) : NamedTagWrapper()
+data class Param(override val root: DocTag, override val name: String) : NamedTagWrapper()
+data class Return(override val root: DocTag) : TagWrapper()
+data class Receiver(override val root: DocTag) : TagWrapper()
+data class Constructor(override val root: DocTag) : TagWrapper()
+data class Throws(override val root: DocTag, override val name: String) : NamedTagWrapper()
+data class Sample(override val root: DocTag, override val name: String) : NamedTagWrapper()
+data class Deprecated(override val root: DocTag) : TagWrapper()
+data class Property(override val root: DocTag, override val name: String) : NamedTagWrapper()
+data class Suppress(override val root: DocTag) : TagWrapper()
+data class CustomTagWrapper(override val root: DocTag, override val name: String) : NamedTagWrapper()
diff --git a/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt b/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt
@@ -1,8 +1,10 @@
 package testApi.testRunner
 
+import org.intellij.markdown.MarkdownElementTypes
 import org.jetbrains.dokka.*
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.*
+import org.jetbrains.dokka.model.doc.CustomDocTag
 import org.jetbrains.dokka.model.doc.Description
 import org.jetbrains.dokka.model.doc.DocumentationNode
 import org.jetbrains.dokka.model.doc.Text
@@ -187,6 +189,6 @@ fun dPackage(
 )
 
 fun documentationNode(vararg texts: String): DocumentationNode {
-    return DocumentationNode(texts.toList().map { Description(Text(it)) })
+    return DocumentationNode(texts.toList().map { Description(CustomDocTag(listOf(Text(it)), name = MarkdownElementTypes.MARKDOWN_FILE.name)) })
 }
 
diff --git a/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt b/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt
@@ -162,6 +162,12 @@ open class MarkdownParser(
         return linksHandler(linkText, link, linkTitle)
     }
 
+    private fun markdownFileHandler(node: ASTNode) =
+        DocTagsFromIElementFactory.getInstance(
+            node.type,
+            children = node.children.evaluateChildren()
+        )
+
     private fun autoLinksHandler(node: ASTNode): DocTag {
         val link = text.substring(node.startOffset + 1, node.endOffset - 1)
 
@@ -206,11 +212,6 @@ open class MarkdownParser(
         body = text.substring(node.startOffset, node.endOffset).transform()
     )
 
-    private fun markdownFileHandler(node: ASTNode) = if (node.children.size == 1)
-        visitNode(node.children.first())
-    else
-        defaultHandler(node)
-
     private fun strikeThroughHandler(node: ASTNode) = DocTagsFromIElementFactory.getInstance(
         node.type,
         children = node.children.evaluateChildrenWithDroppedEnclosingTokens(2)
@@ -448,9 +449,9 @@ open class MarkdownParser(
                             KDocKnownTag.SEE -> See(
                                 parseStringToDocNode(it.getContent()),
                                 it.getSubjectName().orEmpty(),
-                                parseStringToDocNode("[${it.getSubjectName()}]")
+                                (parseStringToDocNode("[${it.getSubjectName()}]"))
                                     .let {
-                                        val link = it.children[0]
+                                        val link = it.children[0].children[0]
                                         if (link is DocumentationLink) link.dri
                                         else null
                                     }

diff --git a/plugins/base/src/main/kotlin/parsers/Parser.kt b/plugins/base/src/main/kotlin/parsers/Parser.kt
@@ -18,8 +18,15 @@ abstract class Parser {
                 "author" -> Author(parseStringToDocNode(it.second))
                 "version" -> Version(parseStringToDocNode(it.second))
                 "since" -> Since(parseStringToDocNode(it.second))
-                "see" -> See(parseStringToDocNode(it.second.substringAfter(' ')), it.second.substringBefore(' '), null)
-                "param" -> Param(parseStringToDocNode(it.second.substringAfter(' ')), it.second.substringBefore(' '))
+                "see" -> See(
+                    parseStringToDocNode(it.second.substringAfter(' ')),
+                    it.second.substringBefore(' '),
+                    null
+                )
+                "param" -> Param(
+                    parseStringToDocNode(it.second.substringAfter(' ')),
+                    it.second.substringBefore(' ')
+                )
                 "property" -> Property(
                     parseStringToDocNode(it.second.substringAfter(' ')),
                     it.second.substringBefore(' ')
@@ -32,7 +39,10 @@ abstract class Parser {
                     it.second.substringBefore(' ')
                 )
                 "deprecated" -> Deprecated(parseStringToDocNode(it.second))
-                "sample" -> Sample(parseStringToDocNode(it.second.substringAfter(' ')), it.second.substringBefore(' '))
+                "sample" -> Sample(
+                    parseStringToDocNode(it.second.substringAfter(' ')),
+                    it.second.substringBefore(' ')
+                )
                 "suppress" -> Suppress(parseStringToDocNode(it.second))
                 else -> CustomTagWrapper(parseStringToDocNode(it.second), it.first)
             }

diff --git a/plugins/base/src/main/kotlin/parsers/factories/DocTagsFromIElementFactory.kt b/plugins/base/src/main/kotlin/parsers/factories/DocTagsFromIElementFactory.kt
@@ -40,6 +40,7 @@ object DocTagsFromIElementFactory {
             GFMElementTypes.HEADER                      -> Th(children, params)
             GFMElementTypes.ROW                         -> Tr(children, params)
             GFMTokenTypes.CELL                          -> Td(children, params)
-            else                                        -> CustomDocTag(children, params)
+            MarkdownElementTypes.MARKDOWN_FILE          -> CustomDocTag(children, params, MarkdownElementTypes.MARKDOWN_FILE.name)
+            else                                        -> CustomDocTag(children, params, type.name)
         }
 }
diff --git a/plugins/base/src/main/kotlin/parsers/factories/DocTagsFromStringFactory.kt b/plugins/base/src/main/kotlin/parsers/factories/DocTagsFromStringFactory.kt
@@ -72,6 +72,6 @@ object DocTagsFromStringFactory {
             "var" -> Var(children, params)
             "documentationlink" -> DocumentationLink(dri ?: throw NullPointerException("DRI cannot be passed null while constructing documentation link!"), children, params)
             "hr" -> HorizontalRule
-            else -> CustomDocTag(children, params)
+            else -> CustomDocTag(children, params, name)
         }
-}
+}
diff --git a/plugins/base/src/main/kotlin/transformers/pages/annotations/SinceKotlinTransformer.kt b/plugins/base/src/main/kotlin/transformers/pages/annotations/SinceKotlinTransformer.kt
@@ -1,7 +1,9 @@
 package org.jetbrains.dokka.base.transformers.pages.annotations
 
+import org.intellij.markdown.MarkdownElementTypes
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.*
+import org.jetbrains.dokka.model.doc.CustomDocTag
 import org.jetbrains.dokka.model.doc.CustomTagWrapper
 import org.jetbrains.dokka.model.doc.Text
 import org.jetbrains.dokka.model.properties.WithExtraProperties
@@ -73,10 +75,19 @@ class SinceKotlinTransformer(val context: DokkaContext) : DocumentableTransforme
                 acc.mapValues {
                     if (it.key == sourceSet) it.value.copy(
                         it.value.children + listOf(
-                            CustomTagWrapper(Text(version.dropWhile { it == '"' }.dropLastWhile { it == '"' }), "Since Kotlin")
+                            CustomTagWrapper(
+                                CustomDocTag(
+                                    listOf(
+                                        Text(version.dropWhile { it == '"' }.dropLastWhile { it == '"' }
+                                        )
+                                    ),
+                                    name = MarkdownElementTypes.MARKDOWN_FILE.name
+                                ),
+                                "Since Kotlin"
+                            )
                         )
                     ) else it.value
                 }
             } ?: acc
         }
-}
+}
diff --git a/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt b/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt
@@ -1,5 +1,6 @@
 package org.jetbrains.dokka.base.transformers.pages.comments
 
+import org.intellij.markdown.MarkdownElementTypes
 import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
 import org.jetbrains.dokka.model.doc.*
 import org.jetbrains.dokka.model.properties.PropertyContainer
@@ -175,7 +176,24 @@ object DocTagToContentConverter : CommentsToContentConverter {
                     styles
                 )
             )
+
+            is CustomDocTag -> if (docTag.isNonemptyFile()) {
+                listOf(
+                    ContentGroup(
+                        buildChildren(docTag),
+                        dci,
+                        sourceSets.toDisplaySourceSets(),
+                        styles,
+                        extra = extra
+                    )
+                )
+            } else {
+                buildChildren(docTag)
+            }
+
             else -> buildChildren(docTag)
         }
     }
+
+    private fun CustomDocTag.isNonemptyFile() = name == MarkdownElementTypes.MARKDOWN_FILE.name && children.size > 1
 }
diff --git a/plugins/base/src/main/kotlin/translators/psi/JavadocParser.kt b/plugins/base/src/main/kotlin/translators/psi/JavadocParser.kt
@@ -6,6 +6,7 @@ import com.intellij.psi.impl.source.tree.JavaDocElementType
 import com.intellij.psi.impl.source.tree.LeafPsiElement
 import com.intellij.psi.javadoc.*
 import com.intellij.psi.util.PsiTreeUtil
+import org.intellij.markdown.MarkdownElementTypes
 import org.jetbrains.dokka.analysis.from
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.doc.*
@@ -55,8 +56,11 @@ class JavadocParser(
         return DocumentationNode(nodes)
     }
 
-    private fun wrapTagIfNecessary(list: List<DocTag>): DocTag =
-        if (list.size == 1) list.first() else P(list)
+    private fun wrapTagIfNecessary(list: List<DocTag>): CustomDocTag =
+        if (list.size == 1 && (list.first() as? CustomDocTag)?.name == MarkdownElementTypes.MARKDOWN_FILE.name)
+            list.first() as CustomDocTag
+        else
+            CustomDocTag(list, name = MarkdownElementTypes.MARKDOWN_FILE.name)
 
     private fun findClosestDocComment(element: PsiNamedElement): PsiDocComment? {
         (element as? PsiDocCommentOwner)?.docComment?.run { return this }

diff --git a/plugins/base/src/test/kotlin/content/params/ContentForParamsTest.kt b/plugins/base/src/test/kotlin/content/params/ContentForParamsTest.kt
@@ -605,6 +605,6 @@ class ContentForParamsTest : AbstractCoreTest() {
     }
 
     private fun DocumentationNode.paramsDescription(): String =
-        children.firstIsInstanceOrNull<Param>()?.root?.children?.firstIsInstanceOrNull<Text>()?.body.orEmpty()
+        children.firstIsInstanceOrNull<Param>()?.root?.children?.first()?.children?.firstIsInstanceOrNull<Text>()?.body.orEmpty()
 
 }
diff --git a/plugins/base/src/test/kotlin/content/seealso/ContentForSeeAlsoTest.kt b/plugins/base/src/test/kotlin/content/seealso/ContentForSeeAlsoTest.kt
@@ -89,7 +89,7 @@ class ContentForSeeAlsoTest : AbstractCoreTest() {
                                             group {
                                                 //DRI should be "test//abc/#/-1/"
                                                 link { +"abc" }
-                                                group { group { } }
+                                                group { }
                                             }
                                         }
                                     }
@@ -201,9 +201,7 @@ class ContentForSeeAlsoTest : AbstractCoreTest() {
                                             group {
                                                 //DRI should be "kotlin.collections/Collection////"
                                                 link { +"Collection" }
-                                                group {
-                                                    group { }
-                                                }
+                                                group { }
                                             }
                                         }
                                     }