Introduce top-level DocTag

7 files changed, 62 insertions, 17 deletions

diff --git a/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt b/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt
index 23e59f8b..e7a36d3f 100644
--- 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
index 894fa82f..228cc88b 100644
--- 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
index 58b4b223..b714caec 100644
--- 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
index 124dc3b4..1af4e719 100644
--- 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)
         }
-}
\ No newline at end of file
+}
diff --git a/plugins/base/src/main/kotlin/transformers/pages/annotations/SinceKotlinTransformer.kt b/plugins/base/src/main/kotlin/transformers/pages/annotations/SinceKotlinTransformer.kt
index 7914e88f..acff5ada 100644
--- 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
         }
-}
\ No newline at end of file
+}
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 51ab0858..0fea6b4f 100644
--- 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
index b4663b20..905d1898 100644
--- 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 }