From b730bf43d93c60df2fc3a1b0b25485b1458a9488 Mon Sep 17 00:00:00 2001
From: Vadim Mishenev <vad-mishenev@yandex.ru>
Date: Fri, 24 Feb 2023 19:16:54 +0200
Subject: Mark Plugin Api as experimental (#2743)

---
 core/src/main/kotlin/plugability/DokkaPlugin.kt | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

(limited to 'core/src')

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(
-- 
cgit