diff options
Diffstat (limited to 'core')
| -rw-r--r-- | core/api/core.api | 8 | ||||
| -rw-r--r-- | core/src/main/kotlin/plugability/DokkaPlugin.kt | 23 |
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( |