Mark Plugin Api as experimental (#2743)

2 files changed, 30 insertions, 1 deletions

diff --git a/core/api/core.api b/core/api/core.api
index 4c755aae..d17c8cb4 100644
--- a/core/api/core.api
+++ b/core/api/core.api
@@ -4394,6 +4394,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
 }
@@ -4402,6 +4403,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;
 }
@@ -4483,6 +4487,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;
diff --git a/core/src/main/kotlin/plugability/DokkaPlugin.kt b/core/src/main/kotlin/plugability/DokkaPlugin.kt
index 625a34e2..b04901e0 100644
--- a/core/src/main/kotlin/plugability/DokkaPlugin.kt
+++ b/core/src/main/kotlin/plugability/DokkaPlugin.kt
@@ -9,6 +9,23 @@ 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<*, *, *>>>()
@@ -16,6 +33,11 @@ abstract class DokkaPlugin {
     @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(