Expose MARKDOWN_FILE constant (#3366)

Kotlin · Mar 20, 2024 · f913a07 · f913a07
1 parent 189b127
commit f913a07
Show file tree

Hide file tree

Showing 23 changed files with 96 additions and 75 deletions.
diff --git a/dokka-subprojects/analysis-java-psi/build.gradle.kts b/dokka-subprojects/analysis-java-psi/build.gradle.kts
@@ -8,6 +8,7 @@ plugins {
 
 dependencies {
     compileOnly(projects.dokkaSubprojects.dokkaCore)
+    compileOnly(projects.dokkaSubprojects.analysisKotlinApi)
 
     api(libs.intellij.java.psi.api)
 

diff --git a/...ava-psi/src/main/kotlin/org/jetbrains/dokka/analysis/java/parsers/JavaDocCommentParser.kt b/...ava-psi/src/main/kotlin/org/jetbrains/dokka/analysis/java/parsers/JavaDocCommentParser.kt
@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package org.jetbrains.dokka.analysis.java.parsers
@@ -19,7 +19,7 @@ import org.jetbrains.dokka.analysis.java.doccomment.DocComment
 import org.jetbrains.dokka.analysis.java.doccomment.JavaDocComment
 import org.jetbrains.dokka.analysis.java.parsers.doctag.PsiDocTagParser
 import org.jetbrains.dokka.analysis.java.util.*
-import org.jetbrains.dokka.analysis.markdown.jb.MARKDOWN_ELEMENT_FILE_NAME
+import org.jetbrains.dokka.analysis.kotlin.markdown.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.doc.*
 import org.jetbrains.dokka.model.doc.Deprecated

diff --git a/dokka-subprojects/analysis-kotlin-api/api/analysis-kotlin-api.api b/dokka-subprojects/analysis-kotlin-api/api/analysis-kotlin-api.api
@@ -69,6 +69,10 @@ public abstract interface class org/jetbrains/dokka/analysis/kotlin/internal/Syn
 	public abstract fun isSynthetic (Lorg/jetbrains/dokka/model/Documentable;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Z
 }
 
+public final class org/jetbrains/dokka/analysis/kotlin/markdown/MarkdownApiKt {
+	public static final field MARKDOWN_ELEMENT_FILE_NAME Ljava/lang/String;
+}
+
 public abstract interface class org/jetbrains/dokka/analysis/kotlin/sample/SampleAnalysisEnvironment {
 	public abstract fun resolveSample (Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Ljava/lang/String;)Lorg/jetbrains/dokka/analysis/kotlin/sample/SampleSnippet;
 }

diff --git a/...is-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/markdown/MarkdownApi.kt b/...is-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/markdown/MarkdownApi.kt
@@ -0,0 +1,21 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.analysis.kotlin.markdown
+
+import org.jetbrains.dokka.model.doc.CustomDocTag
+import org.jetbrains.dokka.model.doc.TagWrapper
+
+/**
+ * This constant is generally used in [CustomDocTag.name] as an indicator that a [CustomDocTag] is a "root" tag
+ * (i.e a container for other tags), which can then be used in [TagWrapper]. However, it might have
+ * other uses around the same area.
+ *
+ * The use and the need for this constant will be revisited in the future, see
+ * [#3404](https://github.com/Kotlin/dokka/issues/3404) for more details.
+ *
+ * The current name and value are chosen for compatibility reasons, because before this constant
+ * was introduced, a different constant named `MARKDOWN_FILE` was used, but it's no longer available.
+ */
+public const val MARKDOWN_ELEMENT_FILE_NAME: String = "MARKDOWN_FILE" // see #3366 and #3404 for more context
diff --git a/dokka-subprojects/analysis-kotlin-descriptors-compiler/build.gradle.kts b/dokka-subprojects/analysis-kotlin-descriptors-compiler/build.gradle.kts
@@ -18,6 +18,7 @@ dependencies {
     testImplementation(kotlin("test"))
     testImplementation(projects.dokkaSubprojects.coreContentMatcherTestUtils)
     testImplementation(projects.dokkaSubprojects.coreTestApi)
+    testImplementation(projects.dokkaSubprojects.analysisKotlinApi)
 
     // TODO [beresnev] get rid of it
     compileOnly(libs.kotlinx.coroutines.core)

diff --git a/...ains/dokka/analysis/kotlin/descriptors/ParseModuleAndPackageDocumentationFragmentsTest.kt b/...ains/dokka/analysis/kotlin/descriptors/ParseModuleAndPackageDocumentationFragmentsTest.kt
@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package org.jetbrains.dokka.analysis.kotlin.descriptors
@@ -8,7 +8,7 @@ package org.jetbrains.dokka.analysis.kotlin.descriptors
 import org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.impl.moduledocs.*
 import org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.impl.moduledocs.ModuleAndPackageDocumentation.Classifier.Module
 import org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.impl.moduledocs.ModuleAndPackageDocumentation.Classifier.Package
-import org.jetbrains.dokka.analysis.markdown.jb.MARKDOWN_ELEMENT_FILE_NAME
+import org.jetbrains.dokka.analysis.kotlin.markdown.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.model.doc.*
 import org.jetbrains.dokka.utilities.DokkaLogger
 import org.junit.jupiter.api.io.TempDir

diff --git a/dokka-subprojects/analysis-markdown-jb/api/analysis-markdown-jb.api b/dokka-subprojects/analysis-markdown-jb/api/analysis-markdown-jb.api
@@ -1,7 +1,3 @@
-public final class org/jetbrains/dokka/analysis/markdown/jb/MarkdownApiKt {
-	public static final fun getMARKDOWN_ELEMENT_FILE_NAME ()Ljava/lang/String;
-}
-
 public class org/jetbrains/dokka/analysis/markdown/jb/MarkdownParser : org/jetbrains/dokka/analysis/markdown/jb/Parser {
 	public static final field Companion Lorg/jetbrains/dokka/analysis/markdown/jb/MarkdownParser$Companion;
 	public fun <init> (Lkotlin/jvm/functions/Function1;Ljava/lang/String;)V

diff --git a/dokka-subprojects/analysis-markdown-jb/build.gradle.kts b/dokka-subprojects/analysis-markdown-jb/build.gradle.kts
@@ -13,6 +13,7 @@ overridePublicationArtifactId("analysis-markdown")
 
 dependencies {
     compileOnly(projects.dokkaSubprojects.dokkaCore)
+    compileOnly(projects.dokkaSubprojects.analysisKotlinApi)
 
     implementation(libs.jsoup)
     implementation(libs.jetbrains.markdown)

diff --git a/...lysis-markdown-jb/src/main/kotlin/org/jetbrains/dokka/analysis/markdown/jb/MarkdownApi.kt b/...lysis-markdown-jb/src/main/kotlin/org/jetbrains/dokka/analysis/markdown/jb/MarkdownApi.kt
diff --git a/...n/kotlin/org/jetbrains/dokka/analysis/markdown/jb/factories/DocTagsFromIElementFactory.kt b/...n/kotlin/org/jetbrains/dokka/analysis/markdown/jb/factories/DocTagsFromIElementFactory.kt
@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package org.jetbrains.dokka.analysis.markdown.jb.factories
@@ -9,7 +9,7 @@ import org.intellij.markdown.MarkdownElementTypes
 import org.intellij.markdown.MarkdownTokenTypes
 import org.intellij.markdown.flavours.gfm.GFMElementTypes
 import org.intellij.markdown.flavours.gfm.GFMTokenTypes
-import org.jetbrains.dokka.analysis.markdown.jb.MARKDOWN_ELEMENT_FILE_NAME
+import org.jetbrains.dokka.analysis.kotlin.markdown.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.analysis.markdown.jb.parseHtmlEncodedWithNormalisedSpaces
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.doc.*

diff --git a/dokka-subprojects/plugin-base/build.gradle.kts b/dokka-subprojects/plugin-base/build.gradle.kts
@@ -43,6 +43,7 @@ dependencies {
     }
     testImplementation(projects.dokkaSubprojects.coreContentMatcherTestUtils)
     testImplementation(projects.dokkaSubprojects.coreTestApi)
+    testImplementation(projects.dokkaSubprojects.analysisKotlinApi)
 
     dokkaHtmlFrontendFiles(projects.dokkaSubprojects.pluginBaseFrontend) {
         because("fetch frontend files from subproject :plugin-base-frontend")

diff --git a/.../kotlin/org/jetbrains/dokka/base/transformers/pages/annotations/SinceKotlinTransformer.kt b/.../kotlin/org/jetbrains/dokka/base/transformers/pages/annotations/SinceKotlinTransformer.kt
@@ -1,13 +1,13 @@
 /*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package org.jetbrains.dokka.base.transformers.pages.annotations
 
 
 import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.Platform
-import org.jetbrains.dokka.analysis.markdown.jb.MARKDOWN_ELEMENT_FILE_NAME
+import org.jetbrains.dokka.analysis.kotlin.markdown.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.base.signatures.KotlinSignatureUtils.annotations
 import org.jetbrains.dokka.model.*
 import org.jetbrains.dokka.model.doc.CustomDocTag

diff --git a/...n/kotlin/org/jetbrains/dokka/base/transformers/pages/comments/DocTagToContentConverter.kt b/...n/kotlin/org/jetbrains/dokka/base/transformers/pages/comments/DocTagToContentConverter.kt
@@ -1,12 +1,12 @@
 /*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package org.jetbrains.dokka.base.transformers.pages.comments
 
 
 import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
-import org.jetbrains.dokka.analysis.markdown.jb.MARKDOWN_ELEMENT_FILE_NAME
+import org.jetbrains.dokka.analysis.kotlin.markdown.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.model.doc.*
 import org.jetbrains.dokka.model.properties.PropertyContainer
 import org.jetbrains.dokka.model.properties.plus

diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/ContentInDescriptionTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/ContentInDescriptionTest.kt
@@ -1,9 +1,10 @@
 /*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package content
 
+import org.jetbrains.dokka.analysis.kotlin.markdown.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.jetbrains.dokka.model.doc.*
 import kotlin.test.Test
@@ -33,7 +34,7 @@ class ContentInDescriptionTest : BaseAbstractTest() {
                 )
             ),
             params = emptyMap(),
-            name = "MARKDOWN_FILE"
+            name = MARKDOWN_ELEMENT_FILE_NAME
         )
     )
 

diff --git a/...gin-base/src/test/kotlin/content/properties/ContentForClassWithParamsAndPropertiesTest.kt b/...gin-base/src/test/kotlin/content/properties/ContentForClassWithParamsAndPropertiesTest.kt
@@ -1,9 +1,10 @@
 /*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package content.properties
 
+import org.jetbrains.dokka.analysis.kotlin.markdown.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.jetbrains.dokka.model.DClass
 import org.jetbrains.dokka.model.dfs
@@ -69,7 +70,7 @@ class ContentForClassWithParamsAndPropertiesTest : BaseAbstractTest() {
                             )
                         )
                     ),
-                    emptyMap(), "MARKDOWN_FILE"
+                    emptyMap(), MARKDOWN_ELEMENT_FILE_NAME
                 )
             )
             val node = rootPage.dfs { it.name == "LoadInitialParams" } as ClasslikePageNode
@@ -92,7 +93,7 @@ class ContentForClassWithParamsAndPropertiesTest : BaseAbstractTest() {
                             )
                         )
                     ),
-                    emptyMap(), "MARKDOWN_FILE"
+                    emptyMap(), MARKDOWN_ELEMENT_FILE_NAME
                 )
             )
             val node = rootPage.dfs { it.name == "LoadInitialParams" } as ClasslikePageNode
@@ -127,7 +128,7 @@ class ContentForClassWithParamsAndPropertiesTest : BaseAbstractTest() {
                             )
                         )
                     ),
-                    emptyMap(), "MARKDOWN_FILE"
+                    emptyMap(), MARKDOWN_ELEMENT_FILE_NAME
                 )
             )
             val node = rootPage.dfs { it.name == "ItemKeyedDataSource" } as ClasslikePageNode
@@ -194,7 +195,7 @@ class ContentForClassWithParamsAndPropertiesTest : BaseAbstractTest() {
                         Text("Defines whether placeholders are enabled, and whether the loaded total count will be ignored.")
                     )
                 )
-            ), emptyMap(), "MARKDOWN_FILE"
+            ), emptyMap(), MARKDOWN_ELEMENT_FILE_NAME
         ),
         name = "placeholdersEnabled"
     )
@@ -219,7 +220,7 @@ class ContentForClassWithParamsAndPropertiesTest : BaseAbstractTest() {
                         Text("Note that this key is generally a hint, and may be ignored if you want to always load from the beginning.")
                     )
                 )
-            ), emptyMap(), "MARKDOWN_FILE"
+            ), emptyMap(), MARKDOWN_ELEMENT_FILE_NAME
         ),
         name = "requestedInitialKey"
     )
@@ -237,7 +238,7 @@ class ContentForClassWithParamsAndPropertiesTest : BaseAbstractTest() {
                         Text("Note that this may be larger than available data.")
                     )
                 )
-            ), emptyMap(), "MARKDOWN_FILE"
+            ), emptyMap(), MARKDOWN_ELEMENT_FILE_NAME
         ),
         name = "requestedLoadSize"
     )
@@ -251,7 +252,7 @@ class ContentForClassWithParamsAndPropertiesTest : BaseAbstractTest() {
                     )
                 )
             ),
-            emptyMap(), "MARKDOWN_FILE"
+            emptyMap(), MARKDOWN_ELEMENT_FILE_NAME
         )
     )
 
@@ -264,7 +265,7 @@ class ContentForClassWithParamsAndPropertiesTest : BaseAbstractTest() {
                     )
                 )
             ),
-            emptyMap(), "MARKDOWN_FILE"
+            emptyMap(), MARKDOWN_ELEMENT_FILE_NAME
         ),
         name = "Key"
     )

diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/markdown/LinkTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/markdown/LinkTest.kt
@@ -1,9 +1,10 @@
 /*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package markdown
 
+import org.jetbrains.dokka.analysis.kotlin.markdown.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.jetbrains.dokka.links.*
 import org.jetbrains.dokka.model.WithGenerics
@@ -172,7 +173,7 @@ class LinkTest : BaseAbstractTest() {
                                 )
                             )
                         ),
-                        name = "MARKDOWN_FILE"
+                        name = MARKDOWN_ELEMENT_FILE_NAME
                     )
                 )
 
@@ -229,7 +230,7 @@ class LinkTest : BaseAbstractTest() {
                                 )
                             )
                         ),
-                        name = "MARKDOWN_FILE"
+                        name = MARKDOWN_ELEMENT_FILE_NAME
                     )
                 )
 

diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/markdown/ParserTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/markdown/ParserTest.kt
@@ -1,12 +1,12 @@
 /*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package org.jetbrains.dokka.tests
 
 import markdown.KDocTest
 
-import org.jetbrains.dokka.analysis.markdown.jb.MARKDOWN_ELEMENT_FILE_NAME
+import org.jetbrains.dokka.analysis.kotlin.markdown.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.analysis.markdown.jb.MarkdownParser
 import org.jetbrains.dokka.model.doc.*
 import kotlin.test.Ignore

diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/model/MultiLanguageInheritanceTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/model/MultiLanguageInheritanceTest.kt
@@ -1,10 +1,11 @@
 /*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package model
 
 import org.jetbrains.dokka.Platform
+import org.jetbrains.dokka.analysis.kotlin.markdown.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.links.PointingToDeclaration
@@ -168,7 +169,7 @@ class MultiLanguageInheritanceTest : BaseAbstractTest() {
 
                     ),
                     params = emptyMap(),
-                    name = "MARKDOWN_FILE"
+                    name = MARKDOWN_ELEMENT_FILE_NAME
                 )
 
                 assertEquals("", module.documentationOf("ChildInJava"))
@@ -246,7 +247,7 @@ class MultiLanguageInheritanceTest : BaseAbstractTest() {
                         )
                     ),
                     params = emptyMap(),
-                    name = "MARKDOWN_FILE"
+                    name = MARKDOWN_ELEMENT_FILE_NAME
                 )
 
                 assertEquals("", module.documentationOf("ChildInJava"))

diff --git a/...gin-base/src/test/kotlin/transformers/ModuleAndPackageDocumentationTransformerUnitTest.kt b/...gin-base/src/test/kotlin/transformers/ModuleAndPackageDocumentationTransformerUnitTest.kt
@@ -1,13 +1,13 @@
 /*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package transformers
 
 
 import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.analysis.kotlin.internal.ModuleAndPackageDocumentationReader
-import org.jetbrains.dokka.analysis.markdown.jb.MARKDOWN_ELEMENT_FILE_NAME
+import org.jetbrains.dokka.analysis.kotlin.markdown.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.base.transformers.documentables.ModuleAndPackageDocumentationTransformer
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.DModule