Reintroduce removed analysis APIs with a deprecation message (#3104)

7 files changed, 254 insertions, 0 deletions

diff --git a/plugins/base/src/main/kotlin/DokkaBase.kt b/plugins/base/src/main/kotlin/DokkaBase.kt
index 6b000ac6..6da71b4b 100644
--- a/plugins/base/src/main/kotlin/DokkaBase.kt
+++ b/plugins/base/src/main/kotlin/DokkaBase.kt
@@ -242,6 +242,50 @@ class DokkaBase : DokkaPlugin() {
         htmlPreprocessors providing ::SearchbarDataInstaller order { after(sourceLinksTransformer) }
     }
 
+    //<editor-fold desc="Deprecated API left for compatibility">
+    @Suppress("DEPRECATION_ERROR")
+    @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    val kotlinAnalysis by extensionPoint<org.jetbrains.dokka.analysis.KotlinAnalysis>()
+
+    @Suppress("DEPRECATION_ERROR")
+    @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    val externalDocumentablesProvider by extensionPoint<org.jetbrains.dokka.base.translators.descriptors.ExternalDocumentablesProvider>()
+
+    @Suppress("DEPRECATION_ERROR")
+    @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    val externalClasslikesTranslator by extensionPoint<org.jetbrains.dokka.base.translators.descriptors.ExternalClasslikesTranslator>()
+
+    @Suppress("DeprecatedCallableAddReplaceWith")
+    @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    val descriptorToDocumentableTranslator: org.jetbrains.dokka.plugability.Extension<org.jetbrains.dokka.transformers.sources.SourceToDocumentableTranslator, *, *>
+        get() = throw org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError()
+
+    @Suppress("DeprecatedCallableAddReplaceWith")
+    @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    val psiToDocumentableTranslator: org.jetbrains.dokka.plugability.Extension<org.jetbrains.dokka.transformers.sources.SourceToDocumentableTranslator, *, *>
+        get() = throw org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError()
+
+    @Suppress("DEPRECATION_ERROR", "DeprecatedCallableAddReplaceWith")
+    @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    val defaultKotlinAnalysis: org.jetbrains.dokka.plugability.Extension<org.jetbrains.dokka.analysis.KotlinAnalysis, *, *>
+        get() = throw org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError()
+
+    @Suppress("DeprecatedCallableAddReplaceWith")
+    @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    val defaultSamplesTransformer: org.jetbrains.dokka.plugability.Extension<PageTransformer, *, *>
+        get() = throw org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError()
+
+    @Suppress("DEPRECATION_ERROR", "DeprecatedCallableAddReplaceWith")
+    @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    val defaultExternalDocumentablesProvider: org.jetbrains.dokka.plugability.Extension<org.jetbrains.dokka.base.translators.descriptors.ExternalDocumentablesProvider, *, *>
+        get() = throw org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError()
+
+    @Suppress("DEPRECATION_ERROR", "DeprecatedCallableAddReplaceWith")
+    @Deprecated(message = org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    val defaultExternalClasslikesTranslator: org.jetbrains.dokka.plugability.Extension<org.jetbrains.dokka.base.translators.descriptors.ExternalClasslikesTranslator, *, *>
+        get() = throw org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError()
+    //</editor-fold>
+
     @OptIn(DokkaPluginApiPreview::class)
     override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
         PluginApiPreviewAcknowledgement
diff --git a/plugins/base/src/main/kotlin/deprecated/AnalysisApiDeprecatedError.kt b/plugins/base/src/main/kotlin/deprecated/AnalysisApiDeprecatedError.kt
new file mode 100644
index 00000000..bc711648
--- /dev/null
+++ b/plugins/base/src/main/kotlin/deprecated/AnalysisApiDeprecatedError.kt
@@ -0,0 +1,12 @@
+package org.jetbrains.dokka.base.deprecated
+
+import org.jetbrains.dokka.InternalDokkaApi
+
+// TODO all API that mentions this message or error can be removed in Dokka >= 2.1
+
+internal const val ANALYSIS_API_DEPRECATION_MESSAGE =
+    "Dokka's Analysis API has been reworked. Please, see the following issue for details and migration options: " +
+            "https://github.com/Kotlin/dokka/issues/3099"
+
+@InternalDokkaApi
+class AnalysisApiDeprecatedError : Error(ANALYSIS_API_DEPRECATION_MESSAGE)
diff --git a/plugins/base/src/main/kotlin/deprecated/KotlinAnalysisDeprecatedApi.kt b/plugins/base/src/main/kotlin/deprecated/KotlinAnalysisDeprecatedApi.kt
new file mode 100644
index 00000000..ad71de2e
--- /dev/null
+++ b/plugins/base/src/main/kotlin/deprecated/KotlinAnalysisDeprecatedApi.kt
@@ -0,0 +1,73 @@
+@file:Suppress("PackageDirectoryMismatch", "FunctionName", "UNUSED_PARAMETER", "unused", "DEPRECATION_ERROR",
+    "DeprecatedCallableAddReplaceWith", "unused"
+)
+
+package org.jetbrains.dokka.analysis
+
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.DokkaSourceSetID
+import org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE
+import org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.utilities.DokkaLogger
+import java.io.Closeable
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+abstract class KotlinAnalysis(
+    private val parent: KotlinAnalysis? = null
+) : Closeable {
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    operator fun get(key: DokkaConfiguration.DokkaSourceSet): AnalysisContext = throw AnalysisApiDeprecatedError()
+
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    operator fun get(key: DokkaSourceSetID): AnalysisContext = throw AnalysisApiDeprecatedError()
+
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    protected abstract fun find(sourceSetID: DokkaSourceSetID): AnalysisContext?
+}
+
+class AnalysisContext(environment: Any, facade: Any, private val analysisEnvironment: Any) : Closeable {
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    val environment: Any get() = throw AnalysisApiDeprecatedError()
+
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    val facade: Any get() = throw AnalysisApiDeprecatedError()
+
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    operator fun component1(): Any = throw AnalysisApiDeprecatedError()
+
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    operator fun component2(): Any = throw AnalysisApiDeprecatedError()
+
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    override fun close() = throw AnalysisApiDeprecatedError()
+}
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+class DokkaAnalysisConfiguration(val ignoreCommonBuiltIns: Boolean = false)
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+fun KotlinAnalysis(context: DokkaContext): KotlinAnalysis = throw AnalysisApiDeprecatedError()
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+fun KotlinAnalysis(
+    sourceSets: List<DokkaConfiguration.DokkaSourceSet>,
+    logger: DokkaLogger,
+    analysisConfiguration: DokkaAnalysisConfiguration = DokkaAnalysisConfiguration()
+): KotlinAnalysis = throw AnalysisApiDeprecatedError()
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+fun ProjectKotlinAnalysis(
+    sourceSets: List<DokkaConfiguration.DokkaSourceSet>,
+    logger: DokkaLogger,
+    analysisConfiguration: DokkaAnalysisConfiguration = DokkaAnalysisConfiguration()
+): KotlinAnalysis = throw AnalysisApiDeprecatedError()
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+fun SamplesKotlinAnalysis(
+    sourceSets: List<DokkaConfiguration.DokkaSourceSet>,
+    logger: DokkaLogger,
+    projectKotlinAnalysis: KotlinAnalysis,
+    analysisConfiguration: DokkaAnalysisConfiguration = DokkaAnalysisConfiguration()
+): KotlinAnalysis = throw AnalysisApiDeprecatedError()
+
diff --git a/plugins/base/src/main/kotlin/deprecated/ParsersDeprecatedAPI.kt b/plugins/base/src/main/kotlin/deprecated/ParsersDeprecatedAPI.kt
new file mode 100644
index 00000000..424c9492
--- /dev/null
+++ b/plugins/base/src/main/kotlin/deprecated/ParsersDeprecatedAPI.kt
@@ -0,0 +1,38 @@
+@file:Suppress("PackageDirectoryMismatch", "DEPRECATION_ERROR", "DeprecatedCallableAddReplaceWith", "unused")
+
+package org.jetbrains.dokka.base.parsers
+
+import org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE
+import org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.doc.DocTag
+import org.jetbrains.dokka.model.doc.DocumentationNode
+import org.jetbrains.dokka.model.doc.TagWrapper
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+abstract class Parser {
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    open fun parseStringToDocNode(extractedString: String): DocTag = throw AnalysisApiDeprecatedError()
+
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    open fun preparse(text: String): String = throw AnalysisApiDeprecatedError()
+
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    open fun parseTagWithBody(tagName: String, content: String): TagWrapper = throw AnalysisApiDeprecatedError()
+}
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+open class MarkdownParser(
+    private val externalDri: (String) -> DRI?,
+    private val kdocLocation: String?,
+) : Parser() {
+    companion object {
+        @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+        fun parseFromKDocTag(
+            @Suppress("UNUSED_PARAMETER") kDocTag: Any?,
+            @Suppress("UNUSED_PARAMETER") externalDri: (String) -> DRI?,
+            @Suppress("UNUSED_PARAMETER") kdocLocation: String?,
+            @Suppress("UNUSED_PARAMETER") parseWithChildren: Boolean = true
+        ): DocumentationNode = throw AnalysisApiDeprecatedError()
+    }
+}
diff --git a/plugins/base/src/main/kotlin/deprecated/ParsersFactoriesDeprecatedAPI.kt b/plugins/base/src/main/kotlin/deprecated/ParsersFactoriesDeprecatedAPI.kt
new file mode 100644
index 00000000..ac6dfd73
--- /dev/null
+++ b/plugins/base/src/main/kotlin/deprecated/ParsersFactoriesDeprecatedAPI.kt
@@ -0,0 +1,20 @@
+@file:Suppress("DeprecatedCallableAddReplaceWith", "PackageDirectoryMismatch", "unused")
+
+package org.jetbrains.dokka.base.parsers.factories
+
+import org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE
+import org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.doc.DocTag
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+object DocTagsFromStringFactory {
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    fun getInstance(
+        @Suppress("UNUSED_PARAMETER") name: String,
+        @Suppress("UNUSED_PARAMETER") children: List<DocTag> = emptyList(),
+        @Suppress("UNUSED_PARAMETER") params: Map<String, String> = emptyMap(),
+        @Suppress("UNUSED_PARAMETER") body: String? = null,
+        @Suppress("UNUSED_PARAMETER") dri: DRI? = null,
+    ): DocTag = throw AnalysisApiDeprecatedError()
+}
diff --git a/plugins/base/src/main/kotlin/deprecated/TranslatorDescriptorsDeprecatedAPI.kt b/plugins/base/src/main/kotlin/deprecated/TranslatorDescriptorsDeprecatedAPI.kt
new file mode 100644
index 00000000..730fb02f
--- /dev/null
+++ b/plugins/base/src/main/kotlin/deprecated/TranslatorDescriptorsDeprecatedAPI.kt
@@ -0,0 +1,46 @@
+@file:Suppress("PackageDirectoryMismatch", "DEPRECATION_ERROR", "DeprecatedCallableAddReplaceWith", "unused")
+
+package org.jetbrains.dokka.base.translators.descriptors
+
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE
+import org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.DClasslike
+import org.jetbrains.dokka.model.DModule
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.transformers.sources.AsyncSourceToDocumentableTranslator
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+fun interface ExternalDocumentablesProvider {
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    fun findClasslike(dri: DRI, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike?
+}
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+class DefaultExternalDocumentablesProvider(
+    @Suppress("UNUSED_PARAMETER") context: DokkaContext
+) : ExternalDocumentablesProvider {
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    override fun findClasslike(dri: DRI, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike =
+        throw AnalysisApiDeprecatedError()
+}
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+fun interface ExternalClasslikesTranslator {
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    fun translateClassDescriptor(descriptor: Any, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike
+}
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+class DefaultDescriptorToDocumentableTranslator(
+    private val context: DokkaContext
+) : AsyncSourceToDocumentableTranslator, ExternalClasslikesTranslator {
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    override suspend fun invokeSuspending(sourceSet: DokkaConfiguration.DokkaSourceSet, context: DokkaContext, ): DModule =
+        throw AnalysisApiDeprecatedError()
+
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    override fun translateClassDescriptor(descriptor: Any, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike =
+        throw AnalysisApiDeprecatedError()
+}
diff --git a/plugins/base/src/main/kotlin/deprecated/TranslatorPsiDeprecatedAPI.kt b/plugins/base/src/main/kotlin/deprecated/TranslatorPsiDeprecatedAPI.kt
new file mode 100644
index 00000000..71766c46
--- /dev/null
+++ b/plugins/base/src/main/kotlin/deprecated/TranslatorPsiDeprecatedAPI.kt
@@ -0,0 +1,21 @@
+@file:Suppress("PackageDirectoryMismatch", "DeprecatedCallableAddReplaceWith", "unused")
+
+package org.jetbrains.dokka.base.translators.psi
+
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.base.deprecated.ANALYSIS_API_DEPRECATION_MESSAGE
+import org.jetbrains.dokka.base.deprecated.AnalysisApiDeprecatedError
+import org.jetbrains.dokka.model.DModule
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.transformers.sources.AsyncSourceToDocumentableTranslator
+
+@Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+class DefaultPsiToDocumentableTranslator(
+    @Suppress("UNUSED_PARAMETER") context: DokkaContext,
+) : AsyncSourceToDocumentableTranslator {
+    @Deprecated(message = ANALYSIS_API_DEPRECATION_MESSAGE, level = DeprecationLevel.ERROR)
+    override suspend fun invokeSuspending(
+        sourceSet: DokkaConfiguration.DokkaSourceSet,
+        context: DokkaContext,
+    ): DModule = throw AnalysisApiDeprecatedError()
+}