Mark Plugin Api as experimental (#2743)

(cherry picked from commit b730bf4)

core/api/core.api

@@ -4387,6 +4387,7 @@ public abstract class org/jetbrains/dokka/plugability/DokkaPlugin {
 	protected final fun extending (Lkotlin/jvm/functions/Function1;)Lorg/jetbrains/dokka/plugability/DokkaPlugin$ExtensionProvider;
 	protected final fun extensionPoint ()Lkotlin/properties/ReadOnlyProperty;
 	public final fun getContext ()Lorg/jetbrains/dokka/plugability/DokkaContext;
+	protected abstract fun pluginApiPreviewAcknowledgement ()Lorg/jetbrains/dokka/plugability/PluginApiPreviewAcknowledgement;
 	public final fun setContext (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
 	protected final fun unsafeInstall (Lkotlin/Lazy;)V
 }
@@ -4395,6 +4396,9 @@ protected final class org/jetbrains/dokka/plugability/DokkaPlugin$ExtensionProvi
 	public final fun provideDelegate (Lorg/jetbrains/dokka/plugability/DokkaPlugin;Lkotlin/reflect/KProperty;)Lkotlin/Lazy;
 }
 
+public abstract interface annotation class org/jetbrains/dokka/plugability/DokkaPluginApiPreview : java/lang/annotation/Annotation {
+}
+
 public final class org/jetbrains/dokka/plugability/DokkaPluginKt {
 	public static final fun throwIllegalQuery ()Ljava/lang/Void;
 }
@@ -4476,6 +4480,10 @@ public final class org/jetbrains/dokka/plugability/OverrideKind$Present : org/je
 	public final fun getOverriden ()Ljava/util/List;
 }
 
+public final class org/jetbrains/dokka/plugability/PluginApiPreviewAcknowledgement {
+	public static final field INSTANCE Lorg/jetbrains/dokka/plugability/PluginApiPreviewAcknowledgement;
+}
+
 public final class org/jetbrains/dokka/plugability/ProvidedExtension {
 	public final fun fromInstance (Ljava/lang/Object;)Lorg/jetbrains/dokka/plugability/ExtensionBuilder;
 	public final fun fromRecipe (Lkotlin/jvm/functions/Function1;)Lorg/jetbrains/dokka/plugability/ExtensionBuilder;

core/src/main/kotlin/plugability/DokkaPlugin.kt

@@ -9,13 +9,35 @@ import kotlin.properties.ReadOnlyProperty
 import kotlin.reflect.KProperty
 import kotlin.reflect.KProperty1
 
+@RequiresOptIn(
+    level = RequiresOptIn.Level.WARNING,
+    message = "All of Dokka's plugin API is in preview and it can be changed " +
+            "in a backwards-incompatible manner with a best-effort migration. " +
+            "By opting in, you acknowledge the risks of relying on preview API."
+)
+@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.FIELD)
+@Retention(AnnotationRetention.BINARY)
+annotation class DokkaPluginApiPreview
+
+/**
+ * Acknowledgement for empty methods that inform users about [DokkaPluginApiPreview]
+ * Also, it allows to not propagates the annotation in IDE by default when a user autogenerate methods.
+ */
+@DokkaPluginApiPreview
+object PluginApiPreviewAcknowledgement
+
 abstract class DokkaPlugin {
     private val extensionDelegates = mutableListOf<KProperty<*>>()
     private val unsafePlugins = mutableListOf<Lazy<Extension<*, *, *>>>()
 
     @PublishedApi
     internal var context: DokkaContext? = null
 
+    /**
+     * @see PluginApiPreviewAcknowledgement
+     */
+    @DokkaPluginApiPreview
+    protected abstract fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement
     protected inline fun <reified T : DokkaPlugin> plugin(): T = context?.plugin(T::class) ?: throwIllegalQuery()
 
     protected fun <T : Any> extensionPoint() = ReadOnlyProperty<DokkaPlugin, ExtensionPoint<T>> { thisRef, property ->
@@ -24,7 +46,6 @@ abstract class DokkaPlugin {
             property.name
         )
     }
-
     protected fun <T : Any> extending(definition: ExtendingDSL.() -> Extension<T, *, *>) = ExtensionProvider(definition)
 
     protected class ExtensionProvider<T : Any> internal constructor(

plugins/all-modules-page/src/main/kotlin/AllModulesPagePlugin.kt

@@ -5,6 +5,8 @@ import org.jetbrains.dokka.base.DokkaBase
 import org.jetbrains.dokka.base.resolvers.local.DokkaLocationProviderFactory
 import org.jetbrains.dokka.base.resolvers.local.LocationProviderFactory
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import org.jetbrains.dokka.templates.TemplatingPlugin
 import org.jetbrains.dokka.transformers.pages.PageCreator
 import org.jetbrains.dokka.transformers.pages.PageTransformer
@@ -45,4 +47,8 @@ class AllModulesPagePlugin : DokkaPlugin() {
     val multiModuleLinkResolver by extending {
         externalModuleLinkResolver providing ::DefaultExternalModuleLinkResolver
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }

plugins/android-documentation/src/main/kotlin/AndroidDocumentationPlugin.kt

@@ -3,11 +3,17 @@ package org.jetbrains.dokka.android
 import org.jetbrains.dokka.android.transformers.HideTagDocumentableFilter
 import org.jetbrains.dokka.base.DokkaBase
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 
 class AndroidDocumentationPlugin : DokkaPlugin() {
     private val dokkaBase by lazy { plugin<DokkaBase>() }
 
     val suppressedByHideTagDocumentableFilter by extending {
         dokkaBase.preMergeDocumentableTransformer providing ::HideTagDocumentableFilter order { before(dokkaBase.emptyPackagesFilter) }
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }

plugins/base/base-test-utils/src/main/kotlin/utils/TestOutputWriter.kt

@@ -3,6 +3,8 @@ package utils
 import org.jetbrains.dokka.base.DokkaBase
 import org.jetbrains.dokka.base.renderers.OutputWriter
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import java.util.*
 
 class TestOutputWriterPlugin(failOnOverwrite: Boolean = true) : DokkaPlugin() {
@@ -15,6 +17,10 @@ class TestOutputWriterPlugin(failOnOverwrite: Boolean = true) : DokkaPlugin() {
                 with writer
                 override dokkaBase.fileWriter)
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }
 
 class TestOutputWriter(private val failOnOverwrite: Boolean = true) : OutputWriter {

plugins/base/src/main/kotlin/DokkaBase.kt

@@ -37,6 +37,8 @@ import org.jetbrains.dokka.base.translators.descriptors.ExternalClasslikesTransl
 import org.jetbrains.dokka.base.translators.descriptors.ExternalDocumentablesProvider
 import org.jetbrains.dokka.base.utils.NoopIntellijLoggerFactory
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import org.jetbrains.dokka.plugability.querySingle
 import org.jetbrains.dokka.renderers.PostAction
 import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer
@@ -292,4 +294,8 @@ class DokkaBase : DokkaPlugin() {
             com.intellij.openapi.diagnostic.Logger.setFactory(NoopIntellijLoggerFactory())
         }
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }

plugins/base/src/test/kotlin/model/InheritorsTest.kt

@@ -11,6 +11,8 @@ 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.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import org.junit.jupiter.api.Assertions.assertTrue
 import org.junit.jupiter.api.Test
 import utils.AbstractModelTest
@@ -165,6 +167,10 @@ class InheritorsTest : AbstractModelTest("/src/main/kotlin/inheritors/Test.kt",
                 )
             } override dokkaBase.defaultKotlinAnalysis
         }
+
+        @OptIn(DokkaPluginApiPreview::class)
+        override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+            PluginApiPreviewAcknowledgement
     }
     @Test
     fun `should inherit docs for stdLib #2638`() {

plugins/base/src/test/kotlin/resourceLinks/ResourceLinksTest.kt

@@ -9,6 +9,8 @@ import org.jetbrains.dokka.base.templating.toJsonString
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.jetbrains.dokka.pages.RootPageNode
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 import org.jsoup.Jsoup
 import org.junit.jupiter.api.Test
@@ -32,6 +34,10 @@ class ResourceLinksTest : BaseAbstractTest() {
         val appender by extending {
             plugin<DokkaBase>().htmlPreprocessors with TestResourcesAppender(resources)
         }
+
+        @OptIn(DokkaPluginApiPreview::class)
+        override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+            PluginApiPreviewAcknowledgement
     }
 
     @Test

plugins/base/src/test/kotlin/transformerBuilders/PageTransformerBuilderTest.kt

@@ -5,6 +5,8 @@ import org.jetbrains.dokka.pages.*
 import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.jetbrains.dokka.model.dfs
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 import org.jetbrains.dokka.transformers.pages.pageMapper
 import org.jetbrains.dokka.transformers.pages.pageScanner
@@ -18,6 +20,10 @@ class PageTransformerBuilderTest : BaseAbstractTest() {
 
     class ProxyPlugin(transformer: PageTransformer) : DokkaPlugin() {
         val pageTransformer by extending { CoreExtensions.pageTransformer with transformer }
+
+        @OptIn(DokkaPluginApiPreview::class)
+        override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+            PluginApiPreviewAcknowledgement
     }
 
     @Test
@@ -136,7 +142,7 @@ class PageTransformerBuilderTest : BaseAbstractTest() {
     }
 
     @Test
-    fun `kotlin constructors should exist even though there is primary constructor only`() {
+    fun `kotlin constructors tab should exist even though there is primary constructor only`() {
         val configuration = dokkaConfiguration {
             sourceSets {
                 sourceSet {

plugins/base/src/test/kotlin/translators/DefaultPsiToDocumentableTranslatorTest.kt

@@ -8,6 +8,8 @@ import org.jetbrains.dokka.links.PointingToDeclaration
 import org.jetbrains.dokka.model.*
 import org.jetbrains.dokka.model.doc.*
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import org.junit.jupiter.api.Assertions.*
 import org.junit.jupiter.api.Test
 import utils.assertNotNull
@@ -327,6 +329,10 @@ class DefaultPsiToDocumentableTranslatorTest : BaseAbstractTest() {
             (dokkaBase.psiToDocumentableTranslator
                     override dokkaBase.descriptorToDocumentableTranslator)
         }
+
+        @OptIn(DokkaPluginApiPreview::class)
+        override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+            PluginApiPreviewAcknowledgement
     }
 
     // for Kotlin classes from DefaultPsiToDocumentableTranslator

plugins/gfm/gfm-template-processing/src/main/kotlin/org/jetbrains/dokka/gfm/templateProcessing/GfmTemplateProcessingPlugin.kt

@@ -6,6 +6,8 @@ import org.jetbrains.dokka.base.DokkaBase
 import org.jetbrains.dokka.gfm.GfmPlugin
 import org.jetbrains.dokka.gfm.location.MarkdownLocationProvider
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import org.jetbrains.dokka.templates.TemplatingPlugin
 
 class GfmTemplateProcessingPlugin : DokkaPlugin() {
@@ -30,4 +32,8 @@ class GfmTemplateProcessingPlugin : DokkaPlugin() {
     val gfmPartialLocationProvider by extending {
         allModulesPagePlugin.partialLocationProviderFactory providing MarkdownLocationProvider::Factory override allModulesPagePlugin.baseLocationProviderFactory
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }

plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/GfmPlugin.kt

@@ -9,6 +9,8 @@ import org.jetbrains.dokka.gfm.location.MarkdownLocationProvider
 import org.jetbrains.dokka.gfm.renderer.BriefCommentPreprocessor
 import org.jetbrains.dokka.gfm.renderer.CommonmarkRenderer
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import org.jetbrains.dokka.renderers.PostAction
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
@@ -50,4 +52,8 @@ class GfmPlugin : DokkaPlugin() {
             }
         }
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }

plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt

@@ -14,6 +14,8 @@ import org.jetbrains.dokka.javadoc.transformers.documentables.JavadocDocumentabl
 import org.jetbrains.dokka.javadoc.validity.MultiplatformConfiguredChecker
 import org.jetbrains.dokka.kotlinAsJava.KotlinAsJavaPlugin
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import org.jetbrains.dokka.renderers.PostAction
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
@@ -94,5 +96,9 @@ class JavadocPlugin : DokkaPlugin() {
             }
         }
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }
 

plugins/jekyll/jekyll-template-processing/src/main/kotlin/org/jetbrains/dokka/gfm/templateProcessing/JekyllTemplateProcessingPlugin.kt

@@ -6,6 +6,8 @@ import org.jetbrains.dokka.base.DokkaBase
 import org.jetbrains.dokka.base.resolvers.local.DokkaLocationProviderFactory
 import org.jetbrains.dokka.jekyll.JekyllPlugin
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 
 class JekyllTemplateProcessingPlugin : DokkaPlugin() {
 
@@ -29,4 +31,8 @@ class JekyllTemplateProcessingPlugin : DokkaPlugin() {
             gfmTemplatingPlugin.gfmPartialLocationProvider
         )
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }

plugins/jekyll/src/main/kotlin/JekyllPlugin.kt

@@ -10,10 +10,7 @@ import org.jetbrains.dokka.gfm.GfmPlugin
 import org.jetbrains.dokka.gfm.renderer.BriefCommentPreprocessor
 import org.jetbrains.dokka.gfm.renderer.CommonmarkRenderer
 import org.jetbrains.dokka.pages.ContentPage
-import org.jetbrains.dokka.plugability.DokkaContext
-import org.jetbrains.dokka.plugability.DokkaPlugin
-import org.jetbrains.dokka.plugability.plugin
-import org.jetbrains.dokka.plugability.query
+import org.jetbrains.dokka.plugability.*
 import org.jetbrains.dokka.renderers.PostAction
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
@@ -59,6 +56,10 @@ class JekyllPlugin : DokkaPlugin() {
             }
         }
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }
 
 class JekyllRenderer(

plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt

@@ -7,6 +7,8 @@ import org.jetbrains.dokka.kotlinAsJava.transformers.JvmNameDocumentableTransfor
 import org.jetbrains.dokka.kotlinAsJava.transformers.KotlinAsJavaDocumentableTransformer
 import org.jetbrains.dokka.kotlinAsJava.translators.KotlinAsJavaDocumentableToPageTranslator
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import org.jetbrains.dokka.renderers.PostAction
 
 class KotlinAsJavaPlugin : DokkaPlugin() {
@@ -38,4 +40,8 @@ class KotlinAsJavaPlugin : DokkaPlugin() {
             }
         }
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }

plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt

@@ -11,6 +11,8 @@ import org.jetbrains.dokka.pages.ContentPage
 import org.jetbrains.dokka.pages.RootPageNode
 import org.jetbrains.dokka.pages.WithDocumentables
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
 class MathjaxPlugin : DokkaPlugin() {
@@ -23,6 +25,10 @@ class MathjaxPlugin : DokkaPlugin() {
             before(plugin<DokkaBase>().sinceKotlinTagContentProvider)
         }
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }
 
 private const val ANNOTATION = "usesMathJax"

plugins/templating/src/main/kotlin/templates/TemplatingPlugin.kt

@@ -3,6 +3,8 @@ package org.jetbrains.dokka.templates
 import org.jetbrains.dokka.allModulesPage.templates.PackageListProcessingStrategy
 import org.jetbrains.dokka.allModulesPage.templates.PagesSearchTemplateStrategy
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 import templates.ProjectNameSubstitutor
 import templates.ReplaceVersionCommandHandler
 import templates.SourcesetDependencyProcessingStrategy
@@ -70,4 +72,8 @@ class TemplatingPlugin : DokkaPlugin() {
     val replaceVersionCommandHandler by extending {
         directiveBasedCommandHandlers providing ::ReplaceVersionCommandHandler
     }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
 }