Stabilize Sample analysis API (#3195)

4 files changed, 57 insertions, 19 deletions

diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/DefaultSamplesTransformer.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/DefaultSamplesTransformer.kt
index 1ba049c8..6e4fef4e 100644
--- a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/DefaultSamplesTransformer.kt
+++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/DefaultSamplesTransformer.kt
@@ -4,6 +4,7 @@
 
 package org.jetbrains.dokka.base.transformers.pages
 
+import org.jetbrains.dokka.analysis.kotlin.KotlinAnalysisPlugin
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.DisplaySourceSet
 import org.jetbrains.dokka.model.doc.Sample
@@ -13,18 +14,18 @@ import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.plugin
 import org.jetbrains.dokka.plugability.querySingle
 import org.jetbrains.dokka.transformers.pages.PageTransformer
-import org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin
-import org.jetbrains.dokka.analysis.kotlin.internal.SampleProvider
-import org.jetbrains.dokka.analysis.kotlin.internal.SampleProviderFactory
+import org.jetbrains.dokka.analysis.kotlin.sample.SampleAnalysisEnvironmentCreator
+import org.jetbrains.dokka.analysis.kotlin.sample.SampleSnippet
 
 internal const val KOTLIN_PLAYGROUND_SCRIPT = "https://unpkg.com/kotlin-playground@1/dist/playground.min.js"
 
 internal class DefaultSamplesTransformer(val context: DokkaContext) : PageTransformer {
 
-    private val sampleProviderFactory: SampleProviderFactory = context.plugin<InternalKotlinAnalysisPlugin>().querySingle { sampleProviderFactory }
+    private val sampleAnalysisEnvironment: SampleAnalysisEnvironmentCreator =
+        context.plugin<KotlinAnalysisPlugin>().querySingle { sampleAnalysisEnvironmentCreator }
 
     override fun invoke(input: RootPageNode): RootPageNode {
-        return sampleProviderFactory.build().use { sampleProvider ->
+        return sampleAnalysisEnvironment.use {
             input.transformContentPagesTree { page ->
                 val samples = (page as? WithDocumentables)?.documentables?.flatMap {
                     it.documentation.entries.flatMap { entry ->
@@ -33,7 +34,7 @@ internal class DefaultSamplesTransformer(val context: DokkaContext) : PageTransf
                 } ?: return@transformContentPagesTree page
 
                 val newContent = samples.fold(page.content) { acc, (sampleSourceSet, sample) ->
-                    sampleProvider.getSample(sampleSourceSet, sample.name)
+                    resolveSample(sampleSourceSet, sample.name)
                         ?.let {
                             acc.addSample(page, sample.name, it)
                         } ?: acc
@@ -51,14 +52,44 @@ internal class DefaultSamplesTransformer(val context: DokkaContext) : PageTransf
     private fun ContentNode.addSample(
         contentPage: ContentPage,
         fqLink: String,
-        sample: SampleProvider.SampleSnippet,
+        sample: SampleSnippet,
     ): ContentNode {
         val node = contentCode(contentPage.content.sourceSets, contentPage.dri, createSampleBody(sample.imports, sample.body), "kotlin")
         return dfs(fqLink, node)
     }
 
-    fun createSampleBody(imports: String, body: String) =
-        """ |$imports
+    /**
+     * If both [imports] and [body] are present, it should return
+     *
+     * ```kotlin
+     * import com.example.One
+     * import com.example.Two
+     *
+     * fun main() {
+     *    //sampleStart
+     *    println("Sample function body")
+     *    println("Another line")
+     *    //sampleEnd
+     * }
+     * ```
+     *
+     * If [imports] are empty, it should return:
+     *
+     * ```kotlin
+     * fun main() {
+     *    //sampleStart
+     *    println("Sample function body")
+     *    println("Another line")
+     *    //sampleEnd
+     * }
+     * ```
+     *
+     * Notice the presence/absence of the new line before the body.
+     */
+    private fun createSampleBody(imports: List<String>, body: String) =
+        // takeIf {} is needed so that joinToString's postfix is not added for empty lists,
+        // and trimMargin() then removes the first empty line
+        """ |${imports.takeIf { it.isNotEmpty() }?.joinToString(separator = "\n", postfix = "\n") { "import $it" } ?: "" }
             |fun main() { 
             |   //sampleStart 
             |   $body 
diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/linkableContent/LinkableContentTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/linkableContent/LinkableContentTest.kt
index 1b73ffee..f03969ac 100644
--- a/dokka-subprojects/plugin-base/src/test/kotlin/linkableContent/LinkableContentTest.kt
+++ b/dokka-subprojects/plugin-base/src/test/kotlin/linkableContent/LinkableContentTest.kt
@@ -6,6 +6,7 @@ package linkableContent
 
 import org.jetbrains.dokka.SourceLinkDefinitionImpl
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import org.jetbrains.dokka.base.transformers.pages.DefaultSamplesTransformer
 import org.jetbrains.dokka.base.transformers.pages.sourcelinks.SourceLinksTransformer
 import org.jetbrains.dokka.model.WithGenerics
 import org.jetbrains.dokka.model.dfs
@@ -192,10 +193,8 @@ class LinkableContentTest : BaseAbstractTest() {
         }
 
         testFromData(configuration) {
-            renderingStage = { rootPageNode, _ ->
-                // TODO [beresnev] :(((
-//                val newRoot = DefaultSamplesTransformer(dokkaContext).invoke(rootPageNode)
-                val newRoot = rootPageNode
+            renderingStage = { rootPageNode, dokkaContext ->
+                val newRoot = DefaultSamplesTransformer(dokkaContext).invoke(rootPageNode)
                 val moduleChildren = newRoot.children
                 assertEquals(1, moduleChildren.size)
                 val packageChildren = moduleChildren.first().children
@@ -212,12 +211,16 @@ class LinkableContentTest : BaseAbstractTest() {
                         .let { it as ContentCodeBlock }.children.single()
                         .let { it as ContentText }.text
                     assertEquals(
-                        """|import p2.${name}Class
-                                |fun main() { 
-                                |   //sampleStart 
-                                |   ${name}Class().printWithExclamation("Hi, $name") 
-                                |   //sampleEnd
-                                |}""".trimMargin(),
+                        """
+                        |import p2.${name}Class
+                        |import kotlin.collections.List
+                        |import kotlin.collections.Map
+                            |
+                            |fun main() { 
+                            |   //sampleStart 
+                            |   ${name}Class().printWithExclamation("Hi, $name") 
+                            |   //sampleEnd
+                            |}""".trimMargin(),
                         text
                     )
                 }
diff --git a/dokka-subprojects/plugin-base/src/test/resources/linkable/samples/jsMain/resources/Samples.kt b/dokka-subprojects/plugin-base/src/test/resources/linkable/samples/jsMain/resources/Samples.kt
index 5dc791d7..3ea25268 100644
--- a/dokka-subprojects/plugin-base/src/test/resources/linkable/samples/jsMain/resources/Samples.kt
+++ b/dokka-subprojects/plugin-base/src/test/resources/linkable/samples/jsMain/resources/Samples.kt
@@ -5,6 +5,8 @@
 package samples
 
 import p2.JsClass
+import kotlin.collections.List
+import kotlin.collections.Map
 
 class SamplesJs {
 
diff --git a/dokka-subprojects/plugin-base/src/test/resources/linkable/samples/jvmMain/resources/Samples.kt b/dokka-subprojects/plugin-base/src/test/resources/linkable/samples/jvmMain/resources/Samples.kt
index f32538cc..0a618b2a 100644
--- a/dokka-subprojects/plugin-base/src/test/resources/linkable/samples/jvmMain/resources/Samples.kt
+++ b/dokka-subprojects/plugin-base/src/test/resources/linkable/samples/jvmMain/resources/Samples.kt
@@ -5,6 +5,8 @@
 package samples
 
 import p2.JvmClass
+import kotlin.collections.List
+import kotlin.collections.Map
 
 class SamplesJvm {