Introduce empty method to mark api as experimental

Kotlin · Jan 31, 2023 · 3439967 · 3439967
1 parent 13ef584
commit 3439967
Show file tree

Hide file tree

Showing 23 changed files with 59 additions and 42 deletions.
diff --git a/core/src/main/kotlin/DokkaGenerator.kt b/core/src/main/kotlin/DokkaGenerator.kt
@@ -7,7 +7,6 @@ import kotlinx.coroutines.Dispatchers
 import org.jetbrains.dokka.generation.GracefulGenerationExit
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.DokkaPlugin
-import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.jetbrains.dokka.utilities.DokkaLogger
 
 /**
@@ -20,7 +19,6 @@ class DokkaGenerator(
     private val logger: DokkaLogger
 ) {
 
-    @OptIn(PreviewDokkaPluginApi::class)
     fun generate() = timed(logger) {
         report("Initializing plugins")
         val context = initializePlugins(configuration, logger)
@@ -38,7 +36,6 @@ class DokkaGenerator(
         finalizeCoroutines()
     }.dump("\n\n === TIME MEASUREMENT ===\n")
 
-    @OptIn(PreviewDokkaPluginApi::class)
     fun initializePlugins(
         configuration: DokkaConfiguration,
         logger: DokkaLogger,

diff --git a/core/src/main/kotlin/plugability/DokkaContext.kt b/core/src/main/kotlin/plugability/DokkaContext.kt
@@ -1,5 +1,3 @@
-@file:OptIn(PreviewDokkaPluginApi::class)
-
 package org.jetbrains.dokka.plugability
 
 import org.jetbrains.dokka.DokkaConfiguration

diff --git a/core/src/main/kotlin/plugability/DokkaJavaPlugin.kt b/core/src/main/kotlin/plugability/DokkaJavaPlugin.kt
@@ -60,7 +60,6 @@ data class ExtensionBuilder<T: Any> internal constructor(
     fun name(name: String) = copy(name = name)
 }
 
-@OptIn(PreviewDokkaPluginApi::class)
 abstract class DokkaJavaPlugin: DokkaPlugin() {
 
     fun <T: DokkaPlugin> plugin(clazz: Class<T>): T =

diff --git a/core/src/main/kotlin/plugability/DokkaPlugin.kt b/core/src/main/kotlin/plugability/DokkaPlugin.kt
@@ -19,14 +19,15 @@ import kotlin.reflect.KProperty1
 @Retention(AnnotationRetention.BINARY)
 annotation class PreviewDokkaPluginApi
 
-@PreviewDokkaPluginApi
 abstract class DokkaPlugin {
     private val extensionDelegates = mutableListOf<KProperty<*>>()
     private val unsafePlugins = mutableListOf<Lazy<Extension<*, *, *>>>()
 
     @PublishedApi
     internal var context: DokkaContext? = null
 
+    @PreviewDokkaPluginApi
+    protected abstract fun previewDokkaPluginApiEmptyMethod()
     protected inline fun <reified T : DokkaPlugin> plugin(): T = context?.plugin(T::class) ?: throwIllegalQuery()
 
     protected fun <T : Any> extensionPoint() = ReadOnlyProperty<DokkaPlugin, ExtensionPoint<T>> { thisRef, property ->
@@ -66,18 +67,15 @@ interface WithUnsafeExtensionSuppression {
 
 interface ConfigurableBlock
 
-@OptIn(PreviewDokkaPluginApi::class)
 inline fun <reified P : DokkaPlugin, reified E : Any> P.query(extension: P.() -> ExtensionPoint<E>): List<E> =
     context?.let { it[extension()] } ?: throwIllegalQuery()
 
-@OptIn(PreviewDokkaPluginApi::class)
 inline fun <reified P : DokkaPlugin, reified E : Any> P.querySingle(extension: P.() -> ExtensionPoint<E>): E =
     context?.single(extension()) ?: throwIllegalQuery()
 
 fun throwIllegalQuery(): Nothing =
     throw IllegalStateException("Querying about plugins is only possible with dokka context initialised")
 
-@OptIn(PreviewDokkaPluginApi::class)
 inline fun <reified T : DokkaPlugin, reified R : ConfigurableBlock> configuration(context: DokkaContext): R? =
     context.configuration.pluginsConfiguration.firstOrNull { it.fqPluginName == T::class.qualifiedName }
         ?.let { configuration ->

diff --git a/core/test-api/src/main/kotlin/testApi/context/MockContext.kt b/core/test-api/src/main/kotlin/testApi/context/MockContext.kt
@@ -1,12 +1,9 @@
-@file:OptIn(PreviewDokkaPluginApi::class)
-
 package org.jetbrains.dokka.testApi.context
 
 import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.plugability.ExtensionPoint
-import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.jetbrains.dokka.utilities.DokkaConsoleLogger
 import org.jetbrains.dokka.utilities.LoggingLevel
 import kotlin.reflect.KClass

diff --git a/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt b/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt
@@ -1,5 +1,3 @@
-@file:OptIn(PreviewDokkaPluginApi::class)
-
 package org.jetbrains.dokka.testApi.testRunner
 
 import com.intellij.openapi.application.PathManager
@@ -8,7 +6,6 @@ import org.jetbrains.dokka.model.DModule
 import org.jetbrains.dokka.pages.RootPageNode
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.DokkaPlugin
-import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.jetbrains.dokka.testApi.logger.TestLogger
 import org.jetbrains.dokka.utilities.DokkaLogger
 import org.junit.rules.TemporaryFolder

diff --git a/plugins/all-modules-page/src/main/kotlin/AllModulesPagePlugin.kt b/plugins/all-modules-page/src/main/kotlin/AllModulesPagePlugin.kt
@@ -10,7 +10,6 @@ import org.jetbrains.dokka.templates.TemplatingPlugin
 import org.jetbrains.dokka.transformers.pages.PageCreator
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
-@OptIn(PreviewDokkaPluginApi::class)
 class AllModulesPagePlugin : DokkaPlugin() {
 
     val partialLocationProviderFactory by extensionPoint<LocationProviderFactory>()
@@ -47,4 +46,8 @@ class AllModulesPagePlugin : DokkaPlugin() {
     val multiModuleLinkResolver by extending {
         externalModuleLinkResolver providing ::DefaultExternalModuleLinkResolver
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
diff --git a/plugins/android-documentation/src/main/kotlin/AndroidDocumentationPlugin.kt b/plugins/android-documentation/src/main/kotlin/AndroidDocumentationPlugin.kt
@@ -5,11 +5,14 @@ import org.jetbrains.dokka.base.DokkaBase
 import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 
-@OptIn(PreviewDokkaPluginApi::class)
 class AndroidDocumentationPlugin : DokkaPlugin() {
     private val dokkaBase by lazy { plugin<DokkaBase>() }
 
     val suppressedByHideTagDocumentableFilter by extending {
         dokkaBase.preMergeDocumentableTransformer providing ::HideTagDocumentableFilter order { before(dokkaBase.emptyPackagesFilter) }
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
diff --git a/plugins/base/base-test-utils/src/main/kotlin/testRunner/baseTestApi.kt b/plugins/base/base-test-utils/src/main/kotlin/testRunner/baseTestApi.kt
@@ -8,14 +8,12 @@ import org.jetbrains.dokka.model.DModule
 import org.jetbrains.dokka.pages.RootPageNode
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.DokkaPlugin
-import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.jetbrains.dokka.testApi.logger.TestLogger
 import org.jetbrains.dokka.testApi.testRunner.*
 import org.jetbrains.dokka.utilities.DokkaConsoleLogger
 import org.jetbrains.dokka.utilities.DokkaLogger
 import org.jetbrains.dokka.utilities.LoggingLevel
 
-@OptIn(PreviewDokkaPluginApi::class)
 class BaseDokkaTestGenerator(
     configuration: DokkaConfiguration,
     logger: DokkaLogger,

diff --git a/plugins/base/base-test-utils/src/main/kotlin/utils/TestOutputWriter.kt b/plugins/base/base-test-utils/src/main/kotlin/utils/TestOutputWriter.kt
@@ -6,7 +6,6 @@ import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import java.util.*
 
-@OptIn(PreviewDokkaPluginApi::class)
 class TestOutputWriterPlugin(failOnOverwrite: Boolean = true) : DokkaPlugin() {
     val writer = TestOutputWriter(failOnOverwrite)
 
@@ -17,6 +16,10 @@ class TestOutputWriterPlugin(failOnOverwrite: Boolean = true) : DokkaPlugin() {
                 with writer
                 override dokkaBase.fileWriter)
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
 
 class TestOutputWriter(private val failOnOverwrite: Boolean = true) : OutputWriter {

diff --git a/plugins/base/src/main/kotlin/DokkaBase.kt b/plugins/base/src/main/kotlin/DokkaBase.kt
@@ -40,7 +40,6 @@ import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
-@OptIn(PreviewDokkaPluginApi::class)
 class DokkaBase : DokkaPlugin() {
 
     val preMergeDocumentableTransformer by extensionPoint<PreMergeDocumentableTransformer>()
@@ -290,4 +289,8 @@ class DokkaBase : DokkaPlugin() {
             com.intellij.openapi.diagnostic.Logger.setFactory(NoopIntellijLoggerFactory())
         }
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
diff --git a/plugins/base/src/test/kotlin/model/InheritorsTest.kt b/plugins/base/src/test/kotlin/model/InheritorsTest.kt
@@ -11,6 +11,7 @@ import org.jetbrains.dokka.model.DInterface
 import org.jetbrains.dokka.model.doc.P
 import org.jetbrains.dokka.model.doc.Text
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.junit.jupiter.api.Assertions.assertTrue
 import org.junit.jupiter.api.Test
 import utils.AbstractModelTest
@@ -163,6 +164,10 @@ class InheritorsTest : AbstractModelTest("/src/main/kotlin/inheritors/Test.kt",
                 )
             } override dokkaBase.defaultKotlinAnalysis
         }
+
+        @PreviewDokkaPluginApi
+        override fun previewDokkaPluginApiEmptyMethod() {
+        }
     }
     @Test
     fun `should inherit docs for stdLib #2638`() {

diff --git a/plugins/build.gradle.kts b/plugins/build.gradle.kts
@@ -1,6 +1,5 @@
 import org.gradle.api.tasks.testing.logging.TestExceptionFormat
 import org.gradle.api.tasks.testing.logging.TestLogEvent
-import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 subprojects {
     apply {
@@ -28,11 +27,4 @@ subprojects {
             showStackTraces = true
         }
     }
-
-    val compileTestKotlin: KotlinCompile by tasks
-    compileTestKotlin.kotlinOptions {
-        freeCompilerArgs = freeCompilerArgs + listOf(
-            "-opt-in=org.jetbrains.dokka.plugability.PreviewDokkaPluginApi"
-        )
-    }
 }
diff --git a/...src/main/kotlin/org/jetbrains/dokka/gfm/templateProcessing/GfmTemplateProcessingPlugin.kt b/...src/main/kotlin/org/jetbrains/dokka/gfm/templateProcessing/GfmTemplateProcessingPlugin.kt
@@ -9,7 +9,6 @@ import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.jetbrains.dokka.templates.TemplatingPlugin
 
-@OptIn(PreviewDokkaPluginApi::class)
 class GfmTemplateProcessingPlugin : DokkaPlugin() {
 
     private val allModulesPagePlugin by lazy { plugin<AllModulesPagePlugin>() }
@@ -32,4 +31,8 @@ class GfmTemplateProcessingPlugin : DokkaPlugin() {
     val gfmPartialLocationProvider by extending {
         allModulesPagePlugin.partialLocationProviderFactory providing MarkdownLocationProvider::Factory override allModulesPagePlugin.baseLocationProviderFactory
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
diff --git a/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/GfmPlugin.kt b/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/GfmPlugin.kt
@@ -13,7 +13,6 @@ import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.jetbrains.dokka.renderers.PostAction
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
-@OptIn(PreviewDokkaPluginApi::class)
 class GfmPlugin : DokkaPlugin() {
 
     val gfmPreprocessors by extensionPoint<PageTransformer>()
@@ -52,4 +51,8 @@ class GfmPlugin : DokkaPlugin() {
             }
         }
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt
@@ -18,7 +18,6 @@ import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.jetbrains.dokka.renderers.PostAction
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
-@OptIn(PreviewDokkaPluginApi::class)
 class JavadocPlugin : DokkaPlugin() {
 
     val dokkaBasePlugin by lazy { plugin<DokkaBase>() }
@@ -96,5 +95,9 @@ class JavadocPlugin : DokkaPlugin() {
             }
         }
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
 
diff --git a/.../main/kotlin/org/jetbrains/dokka/gfm/templateProcessing/JekyllTemplateProcessingPlugin.kt b/.../main/kotlin/org/jetbrains/dokka/gfm/templateProcessing/JekyllTemplateProcessingPlugin.kt
@@ -8,7 +8,6 @@ import org.jetbrains.dokka.jekyll.JekyllPlugin
 import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 
-@OptIn(PreviewDokkaPluginApi::class)
 class JekyllTemplateProcessingPlugin : DokkaPlugin() {
 
     private val allModulesPagePlugin by lazy { plugin<AllModulesPagePlugin>() }
@@ -31,4 +30,8 @@ class JekyllTemplateProcessingPlugin : DokkaPlugin() {
             gfmTemplatingPlugin.gfmPartialLocationProvider
         )
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
diff --git a/plugins/jekyll/src/main/kotlin/JekyllPlugin.kt b/plugins/jekyll/src/main/kotlin/JekyllPlugin.kt
@@ -14,7 +14,6 @@ import org.jetbrains.dokka.plugability.*
 import org.jetbrains.dokka.renderers.PostAction
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
-@OptIn(PreviewDokkaPluginApi::class)
 class JekyllPlugin : DokkaPlugin() {
 
     val jekyllPreprocessors by extensionPoint<PageTransformer>()
@@ -57,6 +56,10 @@ class JekyllPlugin : DokkaPlugin() {
             }
         }
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
 
 class JekyllRenderer(

diff --git a/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt b/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt
@@ -10,7 +10,6 @@ import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.jetbrains.dokka.renderers.PostAction
 
-@OptIn(PreviewDokkaPluginApi::class)
 class KotlinAsJavaPlugin : DokkaPlugin() {
     val kotlinAsJavaDocumentableTransformer by extending {
         CoreExtensions.documentableTransformer with KotlinAsJavaDocumentableTransformer()
@@ -40,4 +39,8 @@ class KotlinAsJavaPlugin : DokkaPlugin() {
             }
         }
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
diff --git a/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt b/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt
@@ -14,7 +14,6 @@ import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
-@OptIn(PreviewDokkaPluginApi::class)
 class MathjaxPlugin : DokkaPlugin() {
     val transformer by extending {
         CoreExtensions.pageTransformer with MathjaxTransformer
@@ -25,6 +24,10 @@ class MathjaxPlugin : DokkaPlugin() {
             before(plugin<DokkaBase>().sinceKotlinTagContentProvider)
         }
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
 
 private const val ANNOTATION = "usesMathJax"

diff --git a/plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt b/plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt
@@ -9,7 +9,6 @@ import templates.ReplaceVersionCommandHandler
 import templates.SourcesetDependencyProcessingStrategy
 
 @Suppress("unused")
-@OptIn(PreviewDokkaPluginApi::class)
 class TemplatingPlugin : DokkaPlugin() {
 
     val submoduleTemplateProcessor by extensionPoint<SubmoduleTemplateProcessor>()
@@ -72,4 +71,8 @@ class TemplatingPlugin : DokkaPlugin() {
     val replaceVersionCommandHandler by extending {
         directiveBasedCommandHandlers providing ::ReplaceVersionCommandHandler
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }
diff --git a/plugins/versioning/src/main/kotlin/org/jetbrains/dokka/versioning/VersioningPlugin.kt b/plugins/versioning/src/main/kotlin/org/jetbrains/dokka/versioning/VersioningPlugin.kt
@@ -7,7 +7,6 @@ import org.jetbrains.dokka.plugability.PreviewDokkaPluginApi
 import org.jetbrains.dokka.plugability.configuration
 import org.jetbrains.dokka.templates.TemplatingPlugin
 
-@OptIn(PreviewDokkaPluginApi::class)
 class VersioningPlugin : DokkaPlugin() {
 
     val versioningStorage by extensionPoint<VersioningStorage>()
@@ -51,4 +50,8 @@ class VersioningPlugin : DokkaPlugin() {
     val previousDocumentationCopyPostAction by extending {
         postActions providing ::DefaultPreviousDocumentationCopyPostAction applyIf { !delayTemplateSubstitution }
     }
+
+    @PreviewDokkaPluginApi
+    override fun previewDokkaPluginApiEmptyMethod() {
+    }
 }