Add DelicateDokkaApi

Kotlin · Apr 26, 2024 · 7685900 · 7685900
1 parent 0d86ee4
commit 7685900
Show file tree

Hide file tree

Showing 6 changed files with 32 additions and 2 deletions.
diff --git a/...ain/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleAnalysisEnvironmentCreator.kt b/...ain/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleAnalysisEnvironmentCreator.kt
@@ -4,6 +4,7 @@
 
 package org.jetbrains.dokka.analysis.kotlin.sample
 
+import org.jetbrains.dokka.DelicateDokkaApi
 import org.jetbrains.dokka.analysis.kotlin.KotlinAnalysisPlugin
 
 /**
@@ -49,5 +50,6 @@ public interface SampleAnalysisEnvironmentCreator {
      *
      * @return a new instance of [SampleAnalysisEnvironment]
      */
+    @DelicateDokkaApi
     public fun create(): SampleAnalysisEnvironment
 }
diff --git a/...kotlin-api/src/test/kotlin/org/jetbrains/dokka/analysis/test/sample/SampleAnalysisTest.kt b/...kotlin-api/src/test/kotlin/org/jetbrains/dokka/analysis/test/sample/SampleAnalysisTest.kt
@@ -4,6 +4,7 @@
 
 package org.jetbrains.dokka.analysis.test.sample
 
+import org.jetbrains.dokka.DelicateDokkaApi
 import org.jetbrains.dokka.analysis.kotlin.sample.SampleSnippet
 import org.jetbrains.dokka.analysis.test.api.kotlinJvmTestProject
 import org.jetbrains.dokka.analysis.test.api.mixedJvmTestProject
@@ -14,6 +15,7 @@ import kotlin.test.*
 
 class SampleAnalysisTest {
 
+    @OptIn(DelicateDokkaApi::class)
     @Test
     fun `should resolve a valid sample if the environment is created manually`() {
         val testProject = kotlinJvmTestProject {
@@ -76,6 +78,7 @@ class SampleAnalysisTest {
         }
     }
 
+    @OptIn(DelicateDokkaApi::class)
     @Test
     fun `should resolve the same sample by multiple environments`() {
         val testProject = kotlinJvmTestProject {

diff --git a/...ns/dokka/analysis/kotlin/descriptors/compiler/impl/DescriptorSampleAnalysisEnvironment.kt b/...ns/dokka/analysis/kotlin/descriptors/compiler/impl/DescriptorSampleAnalysisEnvironment.kt
@@ -10,6 +10,7 @@ import com.intellij.psi.PsiElementVisitor
 import com.intellij.psi.impl.source.tree.LeafPsiElement
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.runBlocking
+import org.jetbrains.dokka.DelicateDokkaApi
 import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.analysis.kotlin.KotlinAnalysisPlugin
 import org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin
@@ -32,7 +33,6 @@ import org.jetbrains.kotlin.resolve.lazy.ResolveSession
 import org.jetbrains.kotlin.resolve.lazy.descriptors.LazyPackageDescriptor
 import org.jetbrains.kotlin.resolve.source.KotlinSourceElement
 import org.jetbrains.kotlin.utils.addToStdlib.applyIf
-import java.io.Closeable
 
 internal class DescriptorSampleAnalysisEnvironmentCreator(
     private val context: DokkaContext,
@@ -54,8 +54,8 @@ internal class DescriptorSampleAnalysisEnvironmentCreator(
         }
     }
 
+    @OptIn(DokkaPluginApiPreview::class, DelicateDokkaApi::class)
     override fun create(): SampleAnalysisEnvironment {
-        @OptIn(DokkaPluginApiPreview::class)
         return DescriptorSampleAnalysisEnvironment(
             kdocFinder = descriptorAnalysisPlugin.querySingle { kdocFinder },
             kotlinAnalysis = SamplesKotlinAnalysis(

diff --git a/...n/org/jetbrains/dokka/analysis/kotlin/symbols/services/SymbolSampleAnalysisEnvironment.kt b/...n/org/jetbrains/dokka/analysis/kotlin/symbols/services/SymbolSampleAnalysisEnvironment.kt
@@ -10,6 +10,7 @@ import com.intellij.psi.PsiElementVisitor
 import com.intellij.psi.impl.source.tree.LeafPsiElement
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.runBlocking
+import org.jetbrains.dokka.DelicateDokkaApi
 import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
 import org.jetbrains.dokka.analysis.kotlin.KotlinAnalysisPlugin
 import org.jetbrains.dokka.analysis.kotlin.sample.SampleAnalysisEnvironment
@@ -50,6 +51,7 @@ internal class SymbolSampleAnalysisEnvironmentCreator(
         }
     }
 
+    @OptIn(DelicateDokkaApi::class)
     override fun create(): SampleAnalysisEnvironment {
         return SymbolSampleAnalysisEnvironment(
             samplesKotlinAnalysis = SamplesKotlinAnalysis(

diff --git a/dokka-subprojects/core/api/dokka-core.api b/dokka-subprojects/core/api/dokka-core.api
@@ -38,6 +38,9 @@ public final class org/jetbrains/dokka/DefaultExternalLinksKt {
 	public static final fun kotlinStdlib (Lorg/jetbrains/dokka/DokkaConfiguration$ExternalDocumentationLink$Companion;)Lorg/jetbrains/dokka/ExternalDocumentationLinkImpl;
 }
 
+public abstract interface annotation class org/jetbrains/dokka/DelicateDokkaApi : java/lang/annotation/Annotation {
+}
+
 public abstract interface class org/jetbrains/dokka/DokkaBootstrap {
 	public abstract fun configure (Ljava/lang/String;Ljava/util/function/BiConsumer;)V
 	public abstract fun generate ()V

diff --git a/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DelicateDokkaApi.kt b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DelicateDokkaApi.kt
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka
+
+/**
+ * Marks declarations in the Dokka that are **delicate** &mdash;
+ * they have limited use-case and shall be used with care in general code.
+ * Any use of a delicate declaration has to be carefully reviewed to make sure it is
+ * properly used and does not create problems like memory and resource leaks.
+ * Carefully read documentation of any declaration marked as `DelicateDokkaApi`.
+ */
+@RequiresOptIn(
+    level = RequiresOptIn.Level.WARNING,
+    message = "This is a delicate API and its use requires care." +
+            " Make sure you fully read and understand documentation of the declaration that is marked as a delicate API."
+)
+@Retention(AnnotationRetention.BINARY)
+public annotation class DelicateDokkaApi