Add documentation

core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt

@@ -113,7 +113,7 @@ public abstract class AbstractTest<M : TestMethods, T : TestBuilder<M>, D : Dokk
             block(tempDir)
         } finally {
             if (cleanUpAfterUse) {
-                tempDir.delete()
+                tempDir.deleteRecursively()
             }
         }
     }

plugins/base/src/main/kotlin/DokkaBase.kt

@@ -33,10 +33,7 @@ import org.jetbrains.dokka.base.translators.documentables.DefaultDocumentableToP
 import org.jetbrains.dokka.generation.Generation
 import org.jetbrains.dokka.plugability.*
 import org.jetbrains.dokka.renderers.Renderer
-import org.jetbrains.dokka.transformers.documentation.DocumentableMerger
-import org.jetbrains.dokka.transformers.documentation.DocumentableToPageTranslator
-import org.jetbrains.dokka.transformers.documentation.DocumentableTransformer
-import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer
+import org.jetbrains.dokka.transformers.documentation.*
 import org.jetbrains.dokka.transformers.pages.PageTransformer
 
 @Suppress("unused")

subprojects/analysis-kotlin-api/build.gradle.kts

@@ -19,6 +19,20 @@ dependencies {
     testImplementation(projects.subprojects.analysisKotlinDescriptors)
 }
 
+disableTestFixturesPublishing()
+
+/**
+ * Test fixtures are automatically published by default, which at this moment in time is unwanted
+ * as the test api is unstable and is internal to the Dokka project, so it shouldn't be used outside of it.
+ *
+ * @see https://docs.gradle.org/current/userguide/java_testing.html#ex-disable-publishing-of-test-fixtures-variants
+ */
+fun disableTestFixturesPublishing() {
+    val javaComponent = components["java"] as AdhocComponentWithVariants
+    javaComponent.withVariantsFromConfiguration(configurations["testFixturesApiElements"]) { skip() }
+    javaComponent.withVariantsFromConfiguration(configurations["testFixturesRuntimeElements"]) { skip() }
+}
+
 registerDokkaArtifactPublication("analysisKotlinApi") {
     artifactId = "analysis-kotlin-api"
 }

subprojects/analysis-kotlin-api/src/test/kotlin/org/jetbrains/dokka/analysis/test/jvm/java/JavaAnalysisTest.kt

@@ -4,15 +4,19 @@
 
 package org.jetbrains.dokka.analysis.test.jvm.java
 
-import org.jetbrains.dokka.analysis.test.api.parseModule
 import org.jetbrains.dokka.analysis.test.api.javaTestProject
+import org.jetbrains.dokka.analysis.test.api.parse
 import kotlin.test.Test
 import kotlin.test.assertEquals
 
 class JavaAnalysisTest {
+
     @Test
-    fun `should parse a Java class`() {
+    fun javaTestProject() {
         val testProject = javaTestProject {
+            dokkaConfiguration {
+                moduleName = "java-module-name-for-unit-test"
+            }
             javaFile(pathFromSrc = "org/jetbrains/dokka/test/java/Bar.java") {
                 +"""
                     public class Bar {
@@ -24,7 +28,8 @@ class JavaAnalysisTest {
             }
         }
 
-        val module = testProject.parseModule()
+        val module = testProject.parse()
+        assertEquals("java-module-name-for-unit-test", module.name)
         assertEquals(1, module.packages.size)
 
         val pckg = module.packages[0]

subprojects/analysis-kotlin-api/src/test/kotlin/org/jetbrains/dokka/analysis/test/jvm/kotlin/KotlinJvmAnalysisTest.kt

@@ -4,21 +4,22 @@
 
 package org.jetbrains.dokka.analysis.test.jvm.kotlin
 
-import org.jetbrains.dokka.analysis.test.api.parseModule
 import org.jetbrains.dokka.analysis.test.api.kotlinJvmTestProject
+import org.jetbrains.dokka.analysis.test.api.parse
 import kotlin.test.Test
 import kotlin.test.assertEquals
 
 class KotlinJvmAnalysisTest {
+
     @Test
-    fun `should parse a top-level class`() {
+    fun kotlinJvmTestProject() {
         val testProject = kotlinJvmTestProject {
             ktFile(pathFromSrc = "org/jetbrains/dokka/test/kotlin/MyFile.kt") {
                 +"public class Foo {}"
             }
         }
 
-        val module = testProject.parseModule()
+        val module = testProject.parse()
         assertEquals(1, module.packages.size)
 
         val pckg = module.packages[0]

subprojects/analysis-kotlin-api/src/test/kotlin/org/jetbrains/dokka/analysis/test/jvm/mixed/MixedJvmAnalysisTest.kt

@@ -4,14 +4,15 @@
 
 package org.jetbrains.dokka.analysis.test.jvm.mixed
 
-import org.jetbrains.dokka.analysis.test.api.parseModule
 import org.jetbrains.dokka.analysis.test.api.mixedJvmTestProject
+import org.jetbrains.dokka.analysis.test.api.parse
 import kotlin.test.Test
 import kotlin.test.assertEquals
 
 class MixedJvmAnalysisTest {
+
     @Test
-    fun `should parse mixed kotlin java classes`() {
+    fun mixedJvmTestProject() {
         val testProject = mixedJvmTestProject {
             kotlinSourceSet {
                 ktFile(pathFromSrc = "test/MyFile.kt") {
@@ -44,7 +45,7 @@ class MixedJvmAnalysisTest {
             }
         }
 
-        val module = testProject.parseModule()
+        val module = testProject.parse()
         assertEquals(1, module.packages.size)
 
         val pckg = module.packages[0]

subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestData.kt

@@ -4,6 +4,18 @@
 
 package org.jetbrains.dokka.analysis.test.api
 
+import org.jetbrains.dokka.analysis.test.api.util.AnalysisTestDslMarker
+
+/**
+ * Represents some sort of data of a [TestProject], which normally consists of a number of [TestDataFile].
+ *
+ * This can be anything that can usually be found in a user-defined project:
+ * programming language source code, markdown files with documentation, samples, etc.
+ *
+ * This virtual test data will be materialized and created physically before running Dokka,
+ * and then passed as input files into it.
+ */
+@AnalysisTestDslMarker
 interface TestData {
     fun getFiles(): List<TestDataFile>
 }

subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestDataFile.kt

@@ -4,9 +4,34 @@
 
 package org.jetbrains.dokka.analysis.test.api
 
-abstract class TestDataFile(pathFromProjectRoot: String) {
+import org.jetbrains.dokka.analysis.test.api.util.AnalysisTestDslMarker
 
-    val pathFromProjectRoot: String = pathFromProjectRoot.removePrefix("/")
+/**
+ * Represents a single file of a project's [TestData].
+ *
+ * This file will be materialized and created physically before running Dokka,
+ * and then passed as one of the input files into it.
+ *
+ * @property pathFromProjectRoot this file's path from the root of the project. Must begin
+ *                               with `/` to not confuse it with relative paths.
+ */
+@AnalysisTestDslMarker
+abstract class TestDataFile(val pathFromProjectRoot: String) {
+
+    init {
+        require(pathFromProjectRoot.startsWith("/")) {
+            "File path going from the project's root must begin with \"/\" to not confuse it with relative paths."
+        }
+    }
 
+    /**
+     * Returns the string contents of this file.
+     *
+     * The contents must be complete, as if the user themselves wrote it. For Kotlin files,
+     * it should return Kotlin source code (including the package and all import statements).
+     * For `.md` files, it should return valid Markdown documentation.
+     *
+     * These contents will be used to populate the real input file to be used by Dokka.
+     */
     abstract fun getContents(): String
 }

subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProject.kt

@@ -4,12 +4,94 @@
 
 package org.jetbrains.dokka.analysis.test.api
 
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.analysis.test.api.analysis.TestAnalysisContext
+import org.jetbrains.dokka.analysis.test.api.analysis.TestAnalysisServices
+import org.jetbrains.dokka.analysis.test.api.analysis.TestProjectAnalyzer
+import org.jetbrains.dokka.analysis.test.api.configuration.BaseTestDokkaConfigurationBuilder
 import org.jetbrains.dokka.analysis.test.api.configuration.TestDokkaConfiguration
+import org.jetbrains.dokka.analysis.test.api.util.withTempDirectory
+import org.jetbrains.dokka.model.DModule
 
+/**
+ * Represents a virtual test project (as if it's user-defined) that will be used to run Dokka.
+ *
+ * A test project consists of some Dokka configuration (represented as [TestDokkaConfiguration])
+ * and some project-specific data like source code and markdown files (represented as [TestData]).
+ *
+ * See [kotlinJvmTestProject], [javaTestProject] and [mixedJvmTestProject] for convenient ways
+ * of bootstrapping test projects.
+ *
+ * See [parse] and [useServices] functions to learn how to run Dokka with this project as input.
+ */
 interface TestProject {
+
+    /**
+     * Verifies that this project is valid from the user's and Dokka's perspectives.
+     * Exists to save time with debugging difficult to catch mistakes, such as copy-pasted
+     * test data that is not applicable to this project.
+     *
+     * Must throw an exception if there's misconfiguration, incorrect / corrupted test data
+     * or API misuse.
+     *
+     * Verification is performed before running Dokka on this project.
+     */
     fun verify()
 
+    /**
+     * Returns the configuration of this project, which will then be mapped to [DokkaConfiguration].
+     *
+     * This is typically constructed using [BaseTestDokkaConfigurationBuilder].
+     */
     fun getConfiguration(): TestDokkaConfiguration
 
+    /**
+     * Returns this project's test data - a collection of source code files, markdown files
+     * and whatever else that can be usually found in a user-defined project.
+     */
     fun getTestData(): TestData
 }
+
+/**
+ * Runs Dokka on the given [TestProject] and returns the generated documentable model.
+ *
+ * Can be used to verify the resulting documentable model, to check that
+ * everything was parsed and converted correctly.
+ *
+ * Usage example:
+ * ```kotlin
+ * val testProject = kotlinJvmTestProject {
+ *     ...
+ * }
+ *
+ * val module: DModule = testProject.parse()
+ * ```
+ */
+fun TestProject.parse(): DModule = TestProjectAnalyzer.parse(this)
+
+/**
+ * Runs Dokka on the given [TestProject] and provides not only the resulting documentable model,
+ * but analysis context and configuration as well, which gives you the ability to call public
+ * analysis services.
+ *
+ * Usage example:
+ *
+ * ```kotlin
+ * val testProject = kotlinJvmTestProject {
+ *     ...
+ * }
+ *
+ * testProject.useServices { context ->
+ *     val pckg: DPackage = context.module.packages.single()
+ *
+ *     // use `moduleAndPackageDocumentationReader` service to get documentation of a package
+ *     val allPackageDocs: SourceSetDependent<DocumentationNode> = moduleAndPackageDocumentationReader.read(pckg)
+ * }
+ * ```
+ */
+fun TestProject.useServices(block: TestAnalysisServices.(context: TestAnalysisContext) -> Unit) {
+    withTempDirectory { tempDirectory ->
+        val (services, context) = TestProjectAnalyzer.analyze(this, tempDirectory)
+        services.block(context)
+    }
+}