Enable explicit API mode (#3139)

5 files changed, 104 insertions, 84 deletions

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 <T : DokkaPlugin> plugin(kclass: KClass<T>): T?
+public interface DokkaContext {
+    public fun <T : DokkaPlugin> plugin(kclass: KClass<T>): T?
 
-    operator fun <T, E> get(point: E): List<T>
+    public operator fun <T, E> get(point: E): List<T>
             where T : Any, E : ExtensionPoint<T>
 
-    fun <T, E> single(point: E): T where T : Any, E : ExtensionPoint<T>
+    public fun <T, E> single(point: E): T where T : Any, E : ExtensionPoint<T>
 
-    val logger: DokkaLogger
-    val configuration: DokkaConfiguration
-    val unusedPoints: Collection<ExtensionPoint<*>>
+    public val logger: DokkaLogger
+    public val configuration: DokkaConfiguration
+    public val unusedPoints: Collection<ExtensionPoint<*>>
 
-    companion object {
-        fun create(
+    public companion object {
+        public fun create(
             configuration: DokkaConfiguration,
             logger: DokkaLogger,
             pluginOverrides: List<DokkaPlugin>
@@ -44,11 +44,11 @@ interface DokkaContext {
     }
 }
 
-inline fun <reified T : DokkaPlugin> DokkaContext.plugin(): T = plugin(T::class)
+public inline fun <reified T : DokkaPlugin> 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 <T: Any>  extensionPoint(ext: ExtensionPoint<T>): ProvidedExtension<T> = ProvidedExtension(ext)
+public class ExtensionBuilderStart internal constructor(){
+    public fun <T: Any>  extensionPoint(ext: ExtensionPoint<T>): ProvidedExtension<T> = ProvidedExtension(ext)
 }
 
-class ProvidedExtension<T: Any> internal constructor(val ext: ExtensionPoint<T>){
-    fun fromInstance(inst: T): ExtensionBuilder<T> = createBuilder(
+public class ProvidedExtension<T: Any> internal constructor(
+    public val ext: ExtensionPoint<T>
+) {
+    public fun fromInstance(inst: T): ExtensionBuilder<T> = createBuilder(
         LazyEvaluated.fromInstance(
             inst
         )
     )
-    fun fromRecipe(recipe: (DokkaContext) -> T): ExtensionBuilder<T> = createBuilder(
+    public fun fromRecipe(recipe: (DokkaContext) -> T): ExtensionBuilder<T> = createBuilder(
         LazyEvaluated.fromRecipe(recipe)
     )
 
@@ -28,7 +30,7 @@ class ProvidedExtension<T: Any> internal constructor(val ext: ExtensionPoint<T>)
             OverrideKind.None, emptyList())
 }
 
-data class ExtensionBuilder<T: Any> internal constructor(
+public data class ExtensionBuilder<T: Any> internal constructor(
     private val name: String,
     private val ext: ExtensionPoint<T>,
     private val action: LazyEvaluated<T>,
@@ -37,7 +39,7 @@ data class ExtensionBuilder<T: Any> internal constructor(
     private val override: OverrideKind = OverrideKind.None,
     private val conditions: List<(DokkaConfiguration) -> Boolean>
 ){
-    fun build(): Extension<T, *, *>  = Extension(
+    public fun build(): Extension<T, *, *>  = Extension(
         ext,
         javaClass.name,
         name,
@@ -50,27 +52,27 @@ data class ExtensionBuilder<T: Any> internal constructor(
         conditions
     )
 
-    fun overrideExtension(extension: Extension<T, *, *>) = copy(override = OverrideKind.Present(listOf(extension)))
+    public fun overrideExtension(extension: Extension<T, *, *>): ExtensionBuilder<T> = copy(override = OverrideKind.Present(listOf(extension)))
 
-    fun newOrdering(before: Array<out Extension<*, *, *>>, after: Array<out Extension<*, *, *>>) =
+    public fun newOrdering(before: Array<out Extension<*, *, *>>, after: Array<out Extension<*, *, *>>): ExtensionBuilder<T> =
         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<T> = copy(before = this.before + exts)
 
-    fun after(vararg exts: Extension<*, *, *>) = copy(after = this.after + exts)
+    public fun after(vararg exts: Extension<*, *, *>): ExtensionBuilder<T> = copy(after = this.after + exts)
 
-    fun addCondition(c: (DokkaConfiguration) -> Boolean) = copy(conditions = conditions + c)
+    public fun addCondition(c: (DokkaConfiguration) -> Boolean): ExtensionBuilder<T> = copy(conditions = conditions + c)
 
-    fun name(name: String) = copy(name = name)
+    public fun name(name: String): ExtensionBuilder<T> = copy(name = name)
 }
 
-abstract class DokkaJavaPlugin: DokkaPlugin() {
+public abstract class DokkaJavaPlugin: DokkaPlugin() {
 
-    fun <T: DokkaPlugin> plugin(clazz: Class<T>): T =
+    public fun <T: DokkaPlugin> plugin(clazz: Class<T>): T =
         context?.plugin(clazz.kotlin) ?: throwIllegalQuery()
 
 
-    fun <T: Any> extend(func: (ExtensionBuilderStart) -> ExtensionBuilder<T>): Lazy<Extension<T, *, *>> =
+    public fun <T: Any> extend(func: (ExtensionBuilderStart) -> ExtensionBuilder<T>): Lazy<Extension<T, *, *>> =
         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<KProperty<*>>()
     private val unsafePlugins = mutableListOf<Lazy<Extension<*, *, *>>>()
 
@@ -47,29 +47,36 @@ abstract class DokkaPlugin {
     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 ->
-        ExtensionPoint(
-            thisRef::class.qualifiedName ?: throw AssertionError("Plugin must be named class"),
-            property.name
-        )
+    protected fun <T : Any> extensionPoint(): ReadOnlyProperty<DokkaPlugin, ExtensionPoint<T>> {
+        return ReadOnlyProperty { thisRef, property ->
+            ExtensionPoint(
+                thisRef::class.qualifiedName ?: throw AssertionError("Plugin must be named class"),
+                property.name
+            )
+        }
+    }
+    protected fun <T : Any> extending(definition: ExtendingDSL.() -> Extension<T, *, *>): ExtensionProvider<T> {
+        return ExtensionProvider(definition)
     }
-    protected fun <T : Any> extending(definition: ExtendingDSL.() -> Extension<T, *, *>) = ExtensionProvider(definition)
 
     protected class ExtensionProvider<T : Any> internal constructor(
         private val definition: ExtendingDSL.() -> Extension<T, *, *>
     ) {
-        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<Extension<T, *, *>> {
+            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<KProperty1<DokkaPlugin, Extension<*, *, *>>>() // 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<Extension<*, *, *>>
+public interface WithUnsafeExtensionSuppression {
+    public val extensionsSuppressed: List<Extension<*, *, *>>
 }
 
-interface ConfigurableBlock
+public interface ConfigurableBlock
 
-inline fun <reified P : DokkaPlugin, reified E : Any> P.query(extension: P.() -> ExtensionPoint<E>): List<E> =
+public inline fun <reified P : DokkaPlugin, reified E : Any> P.query(extension: P.() -> ExtensionPoint<E>): List<E> =
     context?.let { it[extension()] } ?: throwIllegalQuery()
 
-inline fun <reified P : DokkaPlugin, reified E : Any> P.querySingle(extension: P.() -> ExtensionPoint<E>): E =
+public inline fun <reified P : DokkaPlugin, reified E : Any> P.querySingle(extension: P.() -> ExtensionPoint<E>): 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 <reified T : DokkaPlugin, reified R : ConfigurableBlock> configuration(context: DokkaContext): R? =
+public inline fun <reified T : DokkaPlugin, reified R : ConfigurableBlock> 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<T : Any> internal constructor(
+public data class ExtensionPoint<T : Any> 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<Extension<*, *, *>>) : OverrideKind()
+public sealed class OverrideKind {
+    public object None : OverrideKind()
+    public class Present(
+        public val overriden: List<Extension<*, *, *>>
+    ) : OverrideKind()
 }
 
-class Extension<T : Any, Ordering : OrderingKind, Override : OverrideKind> internal constructor(
+public class Extension<T : Any, Ordering : OrderingKind, Override : OverrideKind> internal constructor(
     internal val extensionPoint: ExtensionPoint<T>,
     internal val pluginClass: String,
     internal val extensionName: String,
@@ -32,15 +37,15 @@ class Extension<T : Any, Ordering : OrderingKind, Override : OverrideKind> inter
     internal val override: Override,
     internal val conditions: List<DokkaConfiguration.() -> 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 <T : Any> 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 <T : Any> ExtensionPoint<T>.with(action: T) =
-        Extension(this, this@ExtendingDSL.pluginClass, extensionName, LazyEvaluated.fromInstance(action))
+    public infix fun <T : Any> ExtensionPoint<T>.with(action: T): Extension<T, OrderingKind.None, OverrideKind.None> {
+        return Extension(this, this@ExtendingDSL.pluginClass, extensionName, LazyEvaluated.fromInstance(action))
+    }
 
-    infix fun <T : Any> ExtensionPoint<T>.providing(action: (DokkaContext) -> T) =
-        Extension(this, this@ExtendingDSL.pluginClass, extensionName, LazyEvaluated.fromRecipe(action))
+    public infix fun <T : Any> ExtensionPoint<T>.providing(action: (DokkaContext) -> T): Extension<T, OrderingKind.None, OverrideKind.None> {
+        return Extension(this, this@ExtendingDSL.pluginClass, extensionName, LazyEvaluated.fromRecipe(action))
+    }
 
-    infix fun <T : Any, Override : OverrideKind> Extension<T, OrderingKind.None, Override>.order(
+    public infix fun <T : Any, Override : OverrideKind> Extension<T, OrderingKind.None, Override>.order(
         block: OrderDsl.() -> Unit
-    ) = Extension(extensionPoint, pluginClass, extensionName, action, OrderingKind.ByDsl(block), override, conditions)
+    ): Extension<T, OrderingKind.ByDsl, Override> {
+        return Extension(extensionPoint, pluginClass, extensionName, action, OrderingKind.ByDsl(block), override, conditions)
+    }
 
-    infix fun <T : Any, Override : OverrideKind, Ordering: OrderingKind> Extension<T, Ordering, Override>.applyIf(
+    public infix fun <T : Any, Override : OverrideKind, Ordering: OrderingKind> Extension<T, Ordering, Override>.applyIf(
         condition: DokkaConfiguration.() -> Boolean
-    ) = Extension(extensionPoint, pluginClass, extensionName, action, ordering, override, conditions + condition)
+    ): Extension<T, Ordering, Override> {
+        return Extension(extensionPoint, pluginClass, extensionName, action, ordering, override, conditions + condition)
+    }
 
-    infix fun <T : Any, Override : OverrideKind, Ordering: OrderingKind> Extension<T, Ordering, Override>.override(
+    public infix fun <T : Any, Override : OverrideKind, Ordering: OrderingKind> Extension<T, Ordering, Override>.override(
         overriden: List<Extension<T, *, *>>
-    ) = Extension(extensionPoint, pluginClass, extensionName, action, ordering, OverrideKind.Present(overriden), conditions)
+    ): Extension<T, Ordering, OverrideKind.Present> {
+        return Extension(extensionPoint, pluginClass, extensionName, action, ordering, OverrideKind.Present(overriden), conditions)
+    }
 
-    infix fun <T : Any, Override : OverrideKind, Ordering: OrderingKind> Extension<T, Ordering, Override>.override(
+    public infix fun <T : Any, Override : OverrideKind, Ordering: OrderingKind> Extension<T, Ordering, Override>.override(
         overriden: Extension<T, *, *>
-    ) = this.override(listOf(overriden))
+    ): Extension<T, Ordering, OverrideKind.Present> {
+        return this.override(listOf(overriden))
+    }
 }
 
 @ExtensionsDsl
-class OrderDsl {
+public class OrderDsl {
     internal val previous = mutableSetOf<Extension<*, *, *>>()
     internal val following = mutableSetOf<Extension<*, *, *>>()
 
-    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
     }
 }