From 02f30b142aa467d3a24cc52a1fe3f2fed7ea1e33 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 31 Aug 2023 20:16:01 +0200 Subject: Enable explicit API mode (#3139) --- .../main/kotlin/plugability/DefaultExtensions.kt | 4 -- core/src/main/kotlin/plugability/DokkaContext.kt | 24 +++---- .../src/main/kotlin/plugability/DokkaJavaPlugin.kt | 34 +++++----- core/src/main/kotlin/plugability/DokkaPlugin.kt | 51 ++++++++------- core/src/main/kotlin/plugability/extensions.kt | 75 +++++++++++++--------- 5 files changed, 104 insertions(+), 84 deletions(-) delete mode 100644 core/src/main/kotlin/plugability/DefaultExtensions.kt (limited to 'core/src/main/kotlin/plugability') diff --git a/core/src/main/kotlin/plugability/DefaultExtensions.kt b/core/src/main/kotlin/plugability/DefaultExtensions.kt deleted file mode 100644 index 4dd61777..00000000 --- a/core/src/main/kotlin/plugability/DefaultExtensions.kt +++ /dev/null @@ -1,4 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - diff --git a/core/src/main/kotlin/plugability/DokkaContext.kt b/core/src/main/kotlin/plugability/DokkaContext.kt index faf5f0c1..1287e58b 100644 --- a/core/src/main/kotlin/plugability/DokkaContext.kt +++ b/core/src/main/kotlin/plugability/DokkaContext.kt @@ -12,20 +12,20 @@ import java.util.* import kotlin.reflect.KClass import kotlin.reflect.full.createInstance -interface DokkaContext { - fun plugin(kclass: KClass): T? +public interface DokkaContext { + public fun plugin(kclass: KClass): T? - operator fun get(point: E): List + public operator fun get(point: E): List where T : Any, E : ExtensionPoint - fun single(point: E): T where T : Any, E : ExtensionPoint + public fun single(point: E): T where T : Any, E : ExtensionPoint - val logger: DokkaLogger - val configuration: DokkaConfiguration - val unusedPoints: Collection> + public val logger: DokkaLogger + public val configuration: DokkaConfiguration + public val unusedPoints: Collection> - companion object { - fun create( + public companion object { + public fun create( configuration: DokkaConfiguration, logger: DokkaLogger, pluginOverrides: List @@ -44,11 +44,11 @@ interface DokkaContext { } } -inline fun DokkaContext.plugin(): T = plugin(T::class) +public inline fun DokkaContext.plugin(): T = plugin(T::class) ?: throw java.lang.IllegalStateException("Plugin ${T::class.qualifiedName} is not present in context.") -fun interface DokkaContextConfiguration { - fun installExtension(extension: Extension<*, *, *>) +public fun interface DokkaContextConfiguration { + public fun installExtension(extension: Extension<*, *, *>) } private class DokkaContextConfigurationImpl( diff --git a/core/src/main/kotlin/plugability/DokkaJavaPlugin.kt b/core/src/main/kotlin/plugability/DokkaJavaPlugin.kt index bbea9632..3c2f5e65 100644 --- a/core/src/main/kotlin/plugability/DokkaJavaPlugin.kt +++ b/core/src/main/kotlin/plugability/DokkaJavaPlugin.kt @@ -6,17 +6,19 @@ package org.jetbrains.dokka.plugability import org.jetbrains.dokka.DokkaConfiguration -class ExtensionBuilderStart internal constructor(){ - fun extensionPoint(ext: ExtensionPoint): ProvidedExtension = ProvidedExtension(ext) +public class ExtensionBuilderStart internal constructor(){ + public fun extensionPoint(ext: ExtensionPoint): ProvidedExtension = ProvidedExtension(ext) } -class ProvidedExtension internal constructor(val ext: ExtensionPoint){ - fun fromInstance(inst: T): ExtensionBuilder = createBuilder( +public class ProvidedExtension internal constructor( + public val ext: ExtensionPoint +) { + public fun fromInstance(inst: T): ExtensionBuilder = createBuilder( LazyEvaluated.fromInstance( inst ) ) - fun fromRecipe(recipe: (DokkaContext) -> T): ExtensionBuilder = createBuilder( + public fun fromRecipe(recipe: (DokkaContext) -> T): ExtensionBuilder = createBuilder( LazyEvaluated.fromRecipe(recipe) ) @@ -28,7 +30,7 @@ class ProvidedExtension internal constructor(val ext: ExtensionPoint) OverrideKind.None, emptyList()) } -data class ExtensionBuilder internal constructor( +public data class ExtensionBuilder internal constructor( private val name: String, private val ext: ExtensionPoint, private val action: LazyEvaluated, @@ -37,7 +39,7 @@ data class ExtensionBuilder internal constructor( private val override: OverrideKind = OverrideKind.None, private val conditions: List<(DokkaConfiguration) -> Boolean> ){ - fun build(): Extension = Extension( + public fun build(): Extension = Extension( ext, javaClass.name, name, @@ -50,27 +52,27 @@ data class ExtensionBuilder internal constructor( conditions ) - fun overrideExtension(extension: Extension) = copy(override = OverrideKind.Present(listOf(extension))) + public fun overrideExtension(extension: Extension): ExtensionBuilder = copy(override = OverrideKind.Present(listOf(extension))) - fun newOrdering(before: Array>, after: Array>) = + public fun newOrdering(before: Array>, after: Array>): ExtensionBuilder = copy(before = this.before + before, after = this.after + after) - fun before(vararg exts: Extension<*, *, *>) = copy(before = this.before + exts) + public fun before(vararg exts: Extension<*, *, *>): ExtensionBuilder = copy(before = this.before + exts) - fun after(vararg exts: Extension<*, *, *>) = copy(after = this.after + exts) + public fun after(vararg exts: Extension<*, *, *>): ExtensionBuilder = copy(after = this.after + exts) - fun addCondition(c: (DokkaConfiguration) -> Boolean) = copy(conditions = conditions + c) + public fun addCondition(c: (DokkaConfiguration) -> Boolean): ExtensionBuilder = copy(conditions = conditions + c) - fun name(name: String) = copy(name = name) + public fun name(name: String): ExtensionBuilder = copy(name = name) } -abstract class DokkaJavaPlugin: DokkaPlugin() { +public abstract class DokkaJavaPlugin: DokkaPlugin() { - fun plugin(clazz: Class): T = + public fun plugin(clazz: Class): T = context?.plugin(clazz.kotlin) ?: throwIllegalQuery() - fun extend(func: (ExtensionBuilderStart) -> ExtensionBuilder): Lazy> = + public fun extend(func: (ExtensionBuilderStart) -> ExtensionBuilder): Lazy> = lazy { func(ExtensionBuilderStart()).build() }.also { unsafeInstall(it) } } diff --git a/core/src/main/kotlin/plugability/DokkaPlugin.kt b/core/src/main/kotlin/plugability/DokkaPlugin.kt index 521404e2..7e15c325 100644 --- a/core/src/main/kotlin/plugability/DokkaPlugin.kt +++ b/core/src/main/kotlin/plugability/DokkaPlugin.kt @@ -22,16 +22,16 @@ import kotlin.reflect.KProperty1 ) @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.FIELD) @Retention(AnnotationRetention.BINARY) -annotation class DokkaPluginApiPreview +public 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 +public object PluginApiPreviewAcknowledgement -abstract class DokkaPlugin { +public abstract class DokkaPlugin { private val extensionDelegates = mutableListOf>() private val unsafePlugins = mutableListOf>>() @@ -47,29 +47,36 @@ abstract class DokkaPlugin { protected abstract fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement protected inline fun plugin(): T = context?.plugin(T::class) ?: throwIllegalQuery() - protected fun extensionPoint() = ReadOnlyProperty> { thisRef, property -> - ExtensionPoint( - thisRef::class.qualifiedName ?: throw AssertionError("Plugin must be named class"), - property.name - ) + protected fun extensionPoint(): ReadOnlyProperty> { + return ReadOnlyProperty { thisRef, property -> + ExtensionPoint( + thisRef::class.qualifiedName ?: throw AssertionError("Plugin must be named class"), + property.name + ) + } + } + protected fun extending(definition: ExtendingDSL.() -> Extension): ExtensionProvider { + return ExtensionProvider(definition) } - protected fun extending(definition: ExtendingDSL.() -> Extension) = ExtensionProvider(definition) protected class ExtensionProvider internal constructor( private val definition: ExtendingDSL.() -> Extension ) { - operator fun provideDelegate(thisRef: DokkaPlugin, property: KProperty<*>) = lazy { - ExtendingDSL( - thisRef::class.qualifiedName ?: throw AssertionError("Plugin must be named class"), - property.name - ).definition() - }.also { thisRef.extensionDelegates += property } + public operator fun provideDelegate(thisRef: DokkaPlugin, property: KProperty<*>): Lazy> { + return lazy { + ExtendingDSL( + thisRef::class.qualifiedName ?: throw AssertionError("Plugin must be named class"), + property.name + ).definition() + }.also { thisRef.extensionDelegates += property } + } } internal fun internalInstall(ctx: DokkaContextConfiguration, configuration: DokkaConfiguration) { val extensionsToInstall = extensionDelegates.asSequence() .filterIsInstance>>() // should be always true .map { it.get(this) } + unsafePlugins.map { it.value } + extensionsToInstall.forEach { if (configuration.(it.condition)()) ctx.installExtension(it) } } @@ -78,22 +85,22 @@ abstract class DokkaPlugin { } } -interface WithUnsafeExtensionSuppression { - val extensionsSuppressed: List> +public interface WithUnsafeExtensionSuppression { + public val extensionsSuppressed: List> } -interface ConfigurableBlock +public interface ConfigurableBlock -inline fun P.query(extension: P.() -> ExtensionPoint): List = +public inline fun P.query(extension: P.() -> ExtensionPoint): List = context?.let { it[extension()] } ?: throwIllegalQuery() -inline fun P.querySingle(extension: P.() -> ExtensionPoint): E = +public inline fun P.querySingle(extension: P.() -> ExtensionPoint): E = context?.single(extension()) ?: throwIllegalQuery() -fun throwIllegalQuery(): Nothing = +public fun throwIllegalQuery(): Nothing = throw IllegalStateException("Querying about plugins is only possible with dokka context initialised") -inline fun configuration(context: DokkaContext): R? = +public inline fun configuration(context: DokkaContext): R? = context.configuration.pluginsConfiguration.firstOrNull { it.fqPluginName == T::class.qualifiedName } ?.let { configuration -> when (configuration.serializationFormat) { diff --git a/core/src/main/kotlin/plugability/extensions.kt b/core/src/main/kotlin/plugability/extensions.kt index 813f81b1..04212d1a 100644 --- a/core/src/main/kotlin/plugability/extensions.kt +++ b/core/src/main/kotlin/plugability/extensions.kt @@ -6,24 +6,29 @@ package org.jetbrains.dokka.plugability import org.jetbrains.dokka.DokkaConfiguration -data class ExtensionPoint internal constructor( +public data class ExtensionPoint internal constructor( internal val pluginClass: String, internal val pointName: String ) { - override fun toString() = "ExtensionPoint: $pluginClass/$pointName" + override fun toString(): String = "ExtensionPoint: $pluginClass/$pointName" } -sealed class OrderingKind { - object None : OrderingKind() - class ByDsl(val block: (OrderDsl.() -> Unit)) : OrderingKind() +public sealed class OrderingKind { + public object None : OrderingKind() + + public class ByDsl( + public val block: (OrderDsl.() -> Unit) + ) : OrderingKind() } -sealed class OverrideKind { - object None : OverrideKind() - class Present(val overriden: List>) : OverrideKind() +public sealed class OverrideKind { + public object None : OverrideKind() + public class Present( + public val overriden: List> + ) : OverrideKind() } -class Extension internal constructor( +public class Extension internal constructor( internal val extensionPoint: ExtensionPoint, internal val pluginClass: String, internal val extensionName: String, @@ -32,15 +37,15 @@ class Extension inter internal val override: Override, internal val conditions: List Boolean> ) { - override fun toString() = "Extension: $pluginClass/$extensionName" + override fun toString(): String = "Extension: $pluginClass/$extensionName" - override fun equals(other: Any?) = + override fun equals(other: Any?): Boolean = if (other is Extension<*, *, *>) this.pluginClass == other.pluginClass && this.extensionName == other.extensionName else false - override fun hashCode() = listOf(pluginClass, extensionName).hashCode() + override fun hashCode(): Int = listOf(pluginClass, extensionName).hashCode() - val condition: DokkaConfiguration.() -> Boolean + public val condition: DokkaConfiguration.() -> Boolean get() = { conditions.all { it(this) } } } @@ -52,44 +57,54 @@ internal fun Extension( ) = Extension(extensionPoint, pluginClass, extensionName, action, OrderingKind.None, OverrideKind.None, emptyList()) @DslMarker -annotation class ExtensionsDsl +public annotation class ExtensionsDsl @ExtensionsDsl -class ExtendingDSL(private val pluginClass: String, private val extensionName: String) { +public class ExtendingDSL(private val pluginClass: String, private val extensionName: String) { - infix fun ExtensionPoint.with(action: T) = - Extension(this, this@ExtendingDSL.pluginClass, extensionName, LazyEvaluated.fromInstance(action)) + public infix fun ExtensionPoint.with(action: T): Extension { + return Extension(this, this@ExtendingDSL.pluginClass, extensionName, LazyEvaluated.fromInstance(action)) + } - infix fun ExtensionPoint.providing(action: (DokkaContext) -> T) = - Extension(this, this@ExtendingDSL.pluginClass, extensionName, LazyEvaluated.fromRecipe(action)) + public infix fun ExtensionPoint.providing(action: (DokkaContext) -> T): Extension { + return Extension(this, this@ExtendingDSL.pluginClass, extensionName, LazyEvaluated.fromRecipe(action)) + } - infix fun Extension.order( + public infix fun Extension.order( block: OrderDsl.() -> Unit - ) = Extension(extensionPoint, pluginClass, extensionName, action, OrderingKind.ByDsl(block), override, conditions) + ): Extension { + return Extension(extensionPoint, pluginClass, extensionName, action, OrderingKind.ByDsl(block), override, conditions) + } - infix fun Extension.applyIf( + public infix fun Extension.applyIf( condition: DokkaConfiguration.() -> Boolean - ) = Extension(extensionPoint, pluginClass, extensionName, action, ordering, override, conditions + condition) + ): Extension { + return Extension(extensionPoint, pluginClass, extensionName, action, ordering, override, conditions + condition) + } - infix fun Extension.override( + public infix fun Extension.override( overriden: List> - ) = Extension(extensionPoint, pluginClass, extensionName, action, ordering, OverrideKind.Present(overriden), conditions) + ): Extension { + return Extension(extensionPoint, pluginClass, extensionName, action, ordering, OverrideKind.Present(overriden), conditions) + } - infix fun Extension.override( + public infix fun Extension.override( overriden: Extension - ) = this.override(listOf(overriden)) + ): Extension { + return this.override(listOf(overriden)) + } } @ExtensionsDsl -class OrderDsl { +public class OrderDsl { internal val previous = mutableSetOf>() internal val following = mutableSetOf>() - fun after(vararg extensions: Extension<*, *, *>) { + public fun after(vararg extensions: Extension<*, *, *>) { previous += extensions } - fun before(vararg extensions: Extension<*, *, *>) { + public fun before(vararg extensions: Extension<*, *, *>) { following += extensions } } -- cgit