Stabilize Sample analysis API (#3195)

6 files changed, 133 insertions, 41 deletions

diff --git a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/KotlinAnalysisPlugin.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/KotlinAnalysisPlugin.kt
index 7d434bd5..1df1dfe6 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/KotlinAnalysisPlugin.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/KotlinAnalysisPlugin.kt
@@ -4,17 +4,21 @@
 
 package org.jetbrains.dokka.analysis.kotlin
 
+import org.jetbrains.dokka.analysis.kotlin.sample.SampleAnalysisEnvironmentCreator
+import org.jetbrains.dokka.analysis.kotlin.sample.SampleAnalysisEnvironment
 import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.ExtensionPoint
 import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
 
 public class KotlinAnalysisPlugin : DokkaPlugin() {
 
-    /*
-     * This is where stable public API will go.
+    /**
+     * An extension for analyzing Kotlin sample functions used in the `@sample` KDoc tag.
      *
-     * No stable public API for now.
+     * @see SampleAnalysisEnvironment for more details
      */
+    public val sampleAnalysisEnvironmentCreator: ExtensionPoint<SampleAnalysisEnvironmentCreator> by extensionPoint()
 
     @OptIn(DokkaPluginApiPreview::class)
     override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement = PluginApiPreviewAcknowledgement
diff --git a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt
index 0ef1399a..d032d490 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/InternalKotlinAnalysisPlugin.kt
@@ -31,8 +31,6 @@ public class InternalKotlinAnalysisPlugin : DokkaPlugin() {
 
     public val documentableSourceLanguageParser: ExtensionPoint<DocumentableSourceLanguageParser> by extensionPoint()
 
-    public val sampleProviderFactory: ExtensionPoint<SampleProviderFactory> by extensionPoint()
-
     @OptIn(DokkaPluginApiPreview::class)
     override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement = PluginApiPreviewAcknowledgement
 }
diff --git a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/SampleProvider.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/SampleProvider.kt
deleted file mode 100644
index 472d17f0..00000000
--- a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/internal/SampleProvider.kt
+++ /dev/null
@@ -1,36 +0,0 @@
-/*
- * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-package org.jetbrains.dokka.analysis.kotlin.internal
-
-import org.jetbrains.dokka.DokkaConfiguration
-import org.jetbrains.dokka.InternalDokkaApi
-
-@InternalDokkaApi
-public interface SampleProviderFactory {
-    /**
-     * [SampleProvider] is a short-lived closeable instance.
-     * It assumes that [SampleProvider] scope of use is not big.
-     * Otherwise, it can lead to high memory consumption / leaks during Dokka running.
-     */
-    public fun build(): SampleProvider
-}
-
-/**
- * It is closeable.
- * Otherwise, there is a chance of high memory consumption / leak.
- * In general case, it creates a separate project to analysis samples directories.
- */
-@InternalDokkaApi
-public interface SampleProvider: AutoCloseable {
-    public class SampleSnippet(
-        public val imports: String,
-        public val body: String
-    )
-
-    /**
-     * @return [SampleSnippet] or null if it has not found by [fqLink]
-     */
-    public fun getSample(sourceSet: DokkaConfiguration.DokkaSourceSet, fqLink: String): SampleSnippet?
-}
diff --git a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleAnalysisEnvironment.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleAnalysisEnvironment.kt
new file mode 100644
index 00000000..3620808a
--- /dev/null
+++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleAnalysisEnvironment.kt
@@ -0,0 +1,43 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.analysis.kotlin.sample
+
+import org.jetbrains.dokka.DokkaConfiguration
+
+/**
+ * Fully-configured and ready-to-use sample analysis environment.
+ *
+ * It's best to limit the scope of use and lifetime of this environment as it takes up
+ * additional resources which could be freed once the samples have been analyzed.
+ * Therefore, it's best to use it through the [SampleAnalysisEnvironmentCreator.use] lambda.
+ *
+ * For example, if you need to process all samples in an arbitrary project, it's best to do it
+ * in one iteration and at the same time, so that the environment is created once and lives for
+ * as little is possible, as opposed to creating it again and again for every individual sample.
+ */
+public interface SampleAnalysisEnvironment {
+
+    /**
+     * Resolves a Kotlin sample function by its fully qualified name, and returns its import statements and body.
+     *
+     * @param sourceSet must be either the source set in which this sample function resides, or the source set
+     *                  for which [DokkaConfiguration#samples] or [DokkaConfiguration#sourceRoots]
+     *                  have been configured with the sample's sources.
+     * @param fullyQualifiedLink fully qualified path to the sample function, including all middle packages
+     *                           and the name of the function. Only links to Kotlin functions are valid,
+     *                           which can reside within a class. The package must be the same as the package
+     *                           declared in the sample file. The function must be resolvable by Dokka,
+     *                           meaning it must reside either in the main sources of the project or its
+     *                           sources must be included in [DokkaConfiguration#samples] or
+     *                           [DokkaConfiguration#sourceRoots]. Example: `com.example.pckg.topLevelKotlinFunction`
+     *
+     * @return a sample code snippet which includes import statements and the function body,
+     *         or null if the link could not be resolved (examine the logs to find out the reason).
+     */
+    public fun resolveSample(
+        sourceSet: DokkaConfiguration.DokkaSourceSet,
+        fullyQualifiedLink: String
+    ): SampleSnippet?
+}
diff --git a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleAnalysisEnvironmentCreator.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleAnalysisEnvironmentCreator.kt
new file mode 100644
index 00000000..d64734ef
--- /dev/null
+++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleAnalysisEnvironmentCreator.kt
@@ -0,0 +1,38 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.analysis.kotlin.sample
+
+import org.jetbrains.dokka.analysis.kotlin.KotlinAnalysisPlugin
+
+/**
+ * Entry point to analyzing Kotlin samples.
+ *
+ * Can be acquired via [KotlinAnalysisPlugin.sampleAnalysisEnvironmentCreator].
+ */
+public interface SampleAnalysisEnvironmentCreator {
+
+    /**
+     * Creates and configures the sample analysis environment for a limited-time use.
+     *
+     * Configuring sample analysis environment is a rather expensive operation that takes up additional
+     * resources since Dokka needs to configure and analyze source roots additional to the main ones.
+     * It's best to limit the scope of use and the lifetime of the created environment
+     * so that the resources could be freed as soon as possible.
+     *
+     * No specific cleanup is required by the caller - everything is taken care of automatically
+     * as soon as you exit the [block] block.
+     *
+     * Usage example:
+     * ```kotlin
+     * // create a short-lived environment and resolve all the needed samples
+     * val sample = sampleAnalysisEnvironmentCreator.use {
+     *     resolveSample(sampleSourceSet, "org.jetbrains.dokka.sample.functionName")
+     * }
+     * // process the samples
+     * // ...
+     * ```
+     */
+    public fun <T> use(block: SampleAnalysisEnvironment.() -> T): T
+}
diff --git a/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleSnippet.kt b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleSnippet.kt
new file mode 100644
index 00000000..41b3fa5c
--- /dev/null
+++ b/dokka-subprojects/analysis-kotlin-api/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/sample/SampleSnippet.kt
@@ -0,0 +1,45 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.analysis.kotlin.sample
+
+/**
+ * Represents a sample code snippet of a Kotlin function. The snippet includes both file
+ * import directives (all, even unused) and the sample function body.
+ *
+ * @property imports list of import statement values, without the `import` prefix.
+ *                   Contains no blank lines. Example of a single value: `com.example.pckg.MyClass.function`.
+ * @property body body of the sample function, without the function name or curly braces, only the inner body.
+ *                Common minimal indent of all lines is trimmed. Leading and trailing line breaks are removed.
+ *                Trailing whitespaces are removed. Example: given the sample function `fun foo() { println("foo") }`,
+ *                the sample body will be `println("foo")`.
+ *
+ * @see SampleAnalysisEnvironment for how to acquire it
+ */
+public class SampleSnippet(
+    public val imports: List<String>,
+    public val body: String
+) {
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (javaClass != other?.javaClass) return false
+
+        other as SampleSnippet
+
+        if (imports != other.imports) return false
+        if (body != other.body) return false
+
+        return true
+    }
+
+    override fun hashCode(): Int {
+        var result = imports.hashCode()
+        result = 31 * result + body.hashCode()
+        return result
+    }
+
+    override fun toString(): String {
+        return "SampleSnippet(imports=$imports, body='$body')"
+    }
+}