Skip to content

Commit

Permalink
Mark Plugin Api as experimental (#2743)
Browse files Browse the repository at this point in the history
(cherry picked from commit b730bf4)
  • Loading branch information
vmishenev authored and IgnatBeresnev committed Feb 27, 2023
1 parent 605ce9e commit 5ccda6f
Show file tree
Hide file tree
Showing 20 changed files with 138 additions and 6 deletions.
8 changes: 8 additions & 0 deletions core/api/core.api
Original file line number Diff line number Diff line change
Expand Up @@ -4387,6 +4387,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
}
Expand All @@ -4395,6 +4396,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;
}
Expand Down Expand Up @@ -4476,6 +4480,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;
Expand Down
23 changes: 22 additions & 1 deletion core/src/main/kotlin/plugability/DokkaPlugin.kt
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,35 @@ 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<*, *, *>>>()

@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 ->
Expand All @@ -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(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ import org.jetbrains.dokka.base.DokkaBase
import org.jetbrains.dokka.base.resolvers.local.DokkaLocationProviderFactory
import org.jetbrains.dokka.base.resolvers.local.LocationProviderFactory
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import org.jetbrains.dokka.templates.TemplatingPlugin
import org.jetbrains.dokka.transformers.pages.PageCreator
import org.jetbrains.dokka.transformers.pages.PageTransformer
Expand Down Expand Up @@ -45,4 +47,8 @@ class AllModulesPagePlugin : DokkaPlugin() {
val multiModuleLinkResolver by extending {
externalModuleLinkResolver providing ::DefaultExternalModuleLinkResolver
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,17 @@ package org.jetbrains.dokka.android
import org.jetbrains.dokka.android.transformers.HideTagDocumentableFilter
import org.jetbrains.dokka.base.DokkaBase
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement

class AndroidDocumentationPlugin : DokkaPlugin() {
private val dokkaBase by lazy { plugin<DokkaBase>() }

val suppressedByHideTagDocumentableFilter by extending {
dokkaBase.preMergeDocumentableTransformer providing ::HideTagDocumentableFilter order { before(dokkaBase.emptyPackagesFilter) }
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ package utils
import org.jetbrains.dokka.base.DokkaBase
import org.jetbrains.dokka.base.renderers.OutputWriter
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import java.util.*

class TestOutputWriterPlugin(failOnOverwrite: Boolean = true) : DokkaPlugin() {
Expand All @@ -15,6 +17,10 @@ class TestOutputWriterPlugin(failOnOverwrite: Boolean = true) : DokkaPlugin() {
with writer
override dokkaBase.fileWriter)
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}

class TestOutputWriter(private val failOnOverwrite: Boolean = true) : OutputWriter {
Expand Down
6 changes: 6 additions & 0 deletions plugins/base/src/main/kotlin/DokkaBase.kt
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ import org.jetbrains.dokka.base.translators.descriptors.ExternalClasslikesTransl
import org.jetbrains.dokka.base.translators.descriptors.ExternalDocumentablesProvider
import org.jetbrains.dokka.base.utils.NoopIntellijLoggerFactory
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import org.jetbrains.dokka.plugability.querySingle
import org.jetbrains.dokka.renderers.PostAction
import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer
Expand Down Expand Up @@ -292,4 +294,8 @@ class DokkaBase : DokkaPlugin() {
com.intellij.openapi.diagnostic.Logger.setFactory(NoopIntellijLoggerFactory())
}
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}
6 changes: 6 additions & 0 deletions plugins/base/src/test/kotlin/model/InheritorsTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ import org.jetbrains.dokka.model.DInterface
import org.jetbrains.dokka.model.doc.P
import org.jetbrains.dokka.model.doc.Text
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test
import utils.AbstractModelTest
Expand Down Expand Up @@ -165,6 +167,10 @@ class InheritorsTest : AbstractModelTest("/src/main/kotlin/inheritors/Test.kt",
)
} override dokkaBase.defaultKotlinAnalysis
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}
@Test
fun `should inherit docs for stdLib #2638`() {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ import org.jetbrains.dokka.base.templating.toJsonString
import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
import org.jetbrains.dokka.pages.RootPageNode
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import org.jetbrains.dokka.transformers.pages.PageTransformer
import org.jsoup.Jsoup
import org.junit.jupiter.api.Test
Expand All @@ -32,6 +34,10 @@ class ResourceLinksTest : BaseAbstractTest() {
val appender by extending {
plugin<DokkaBase>().htmlPreprocessors with TestResourcesAppender(resources)
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}

@Test
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ import org.jetbrains.dokka.pages.*
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
import org.jetbrains.dokka.model.dfs
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import org.jetbrains.dokka.transformers.pages.PageTransformer
import org.jetbrains.dokka.transformers.pages.pageMapper
import org.jetbrains.dokka.transformers.pages.pageScanner
Expand All @@ -18,6 +20,10 @@ class PageTransformerBuilderTest : BaseAbstractTest() {

class ProxyPlugin(transformer: PageTransformer) : DokkaPlugin() {
val pageTransformer by extending { CoreExtensions.pageTransformer with transformer }

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}

@Test
Expand Down Expand Up @@ -136,7 +142,7 @@ class PageTransformerBuilderTest : BaseAbstractTest() {
}

@Test
fun `kotlin constructors should exist even though there is primary constructor only`() {
fun `kotlin constructors tab should exist even though there is primary constructor only`() {
val configuration = dokkaConfiguration {
sourceSets {
sourceSet {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ import org.jetbrains.dokka.links.PointingToDeclaration
import org.jetbrains.dokka.model.*
import org.jetbrains.dokka.model.doc.*
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import org.junit.jupiter.api.Assertions.*
import org.junit.jupiter.api.Test
import utils.assertNotNull
Expand Down Expand Up @@ -327,6 +329,10 @@ class DefaultPsiToDocumentableTranslatorTest : BaseAbstractTest() {
(dokkaBase.psiToDocumentableTranslator
override dokkaBase.descriptorToDocumentableTranslator)
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}

// for Kotlin classes from DefaultPsiToDocumentableTranslator
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ import org.jetbrains.dokka.base.DokkaBase
import org.jetbrains.dokka.gfm.GfmPlugin
import org.jetbrains.dokka.gfm.location.MarkdownLocationProvider
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import org.jetbrains.dokka.templates.TemplatingPlugin

class GfmTemplateProcessingPlugin : DokkaPlugin() {
Expand All @@ -30,4 +32,8 @@ class GfmTemplateProcessingPlugin : DokkaPlugin() {
val gfmPartialLocationProvider by extending {
allModulesPagePlugin.partialLocationProviderFactory providing MarkdownLocationProvider::Factory override allModulesPagePlugin.baseLocationProviderFactory
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ import org.jetbrains.dokka.gfm.location.MarkdownLocationProvider
import org.jetbrains.dokka.gfm.renderer.BriefCommentPreprocessor
import org.jetbrains.dokka.gfm.renderer.CommonmarkRenderer
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import org.jetbrains.dokka.renderers.PostAction
import org.jetbrains.dokka.transformers.pages.PageTransformer

Expand Down Expand Up @@ -50,4 +52,8 @@ class GfmPlugin : DokkaPlugin() {
}
}
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ import org.jetbrains.dokka.javadoc.transformers.documentables.JavadocDocumentabl
import org.jetbrains.dokka.javadoc.validity.MultiplatformConfiguredChecker
import org.jetbrains.dokka.kotlinAsJava.KotlinAsJavaPlugin
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import org.jetbrains.dokka.renderers.PostAction
import org.jetbrains.dokka.transformers.pages.PageTransformer

Expand Down Expand Up @@ -94,5 +96,9 @@ class JavadocPlugin : DokkaPlugin() {
}
}
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}

Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ import org.jetbrains.dokka.base.DokkaBase
import org.jetbrains.dokka.base.resolvers.local.DokkaLocationProviderFactory
import org.jetbrains.dokka.jekyll.JekyllPlugin
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement

class JekyllTemplateProcessingPlugin : DokkaPlugin() {

Expand All @@ -29,4 +31,8 @@ class JekyllTemplateProcessingPlugin : DokkaPlugin() {
gfmTemplatingPlugin.gfmPartialLocationProvider
)
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}
9 changes: 5 additions & 4 deletions plugins/jekyll/src/main/kotlin/JekyllPlugin.kt
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,7 @@ import org.jetbrains.dokka.gfm.GfmPlugin
import org.jetbrains.dokka.gfm.renderer.BriefCommentPreprocessor
import org.jetbrains.dokka.gfm.renderer.CommonmarkRenderer
import org.jetbrains.dokka.pages.ContentPage
import org.jetbrains.dokka.plugability.DokkaContext
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.plugin
import org.jetbrains.dokka.plugability.query
import org.jetbrains.dokka.plugability.*
import org.jetbrains.dokka.renderers.PostAction
import org.jetbrains.dokka.transformers.pages.PageTransformer

Expand Down Expand Up @@ -59,6 +56,10 @@ class JekyllPlugin : DokkaPlugin() {
}
}
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}

class JekyllRenderer(
Expand Down
6 changes: 6 additions & 0 deletions plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ import org.jetbrains.dokka.kotlinAsJava.transformers.JvmNameDocumentableTransfor
import org.jetbrains.dokka.kotlinAsJava.transformers.KotlinAsJavaDocumentableTransformer
import org.jetbrains.dokka.kotlinAsJava.translators.KotlinAsJavaDocumentableToPageTranslator
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import org.jetbrains.dokka.renderers.PostAction

class KotlinAsJavaPlugin : DokkaPlugin() {
Expand Down Expand Up @@ -38,4 +40,8 @@ class KotlinAsJavaPlugin : DokkaPlugin() {
}
}
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}
6 changes: 6 additions & 0 deletions plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ import org.jetbrains.dokka.pages.ContentPage
import org.jetbrains.dokka.pages.RootPageNode
import org.jetbrains.dokka.pages.WithDocumentables
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import org.jetbrains.dokka.transformers.pages.PageTransformer

class MathjaxPlugin : DokkaPlugin() {
Expand All @@ -23,6 +25,10 @@ class MathjaxPlugin : DokkaPlugin() {
before(plugin<DokkaBase>().sinceKotlinTagContentProvider)
}
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}

private const val ANNOTATION = "usesMathJax"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ package org.jetbrains.dokka.templates
import org.jetbrains.dokka.allModulesPage.templates.PackageListProcessingStrategy
import org.jetbrains.dokka.allModulesPage.templates.PagesSearchTemplateStrategy
import org.jetbrains.dokka.plugability.DokkaPlugin
import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
import templates.ProjectNameSubstitutor
import templates.ReplaceVersionCommandHandler
import templates.SourcesetDependencyProcessingStrategy
Expand Down Expand Up @@ -70,4 +72,8 @@ class TemplatingPlugin : DokkaPlugin() {
val replaceVersionCommandHandler by extending {
directiveBasedCommandHandlers providing ::ReplaceVersionCommandHandler
}

@OptIn(DokkaPluginApiPreview::class)
override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
PluginApiPreviewAcknowledgement
}
Loading

0 comments on commit 5ccda6f

Please sign in to comment.