From 8e5c63d035ef44a269b8c43430f43f5c8eebfb63 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Fri, 10 Nov 2023 11:46:54 +0100 Subject: Restructure the project to utilize included builds (#3174) * Refactor and simplify artifact publishing * Update Gradle to 8.4 * Refactor and simplify convention plugins and build scripts Fixes #3132 --------- Co-authored-by: Adam <897017+aSemy@users.noreply.github.com> Co-authored-by: Oleg Yukhnevich --- .../jetbrains/dokka/analysis/test/api/TestData.kt | 21 -- .../dokka/analysis/test/api/TestDataFile.kt | 37 ---- .../dokka/analysis/test/api/TestProject.kt | 97 --------- .../dokka/analysis/test/api/TestProjectFactory.kt | 67 ------- .../test/api/analysis/TestAnalysisContext.kt | 36 ---- .../test/api/analysis/TestAnalysisServices.kt | 20 -- .../test/api/analysis/TestProjectAnalyzer.kt | 223 --------------------- .../api/configuration/TestDokkaConfiguration.kt | 171 ---------------- .../configuration/TestDokkaConfigurationBuilder.kt | 145 -------------- .../configuration/TestDokkaConfigurationMapper.kt | 177 ---------------- .../test/api/jvm/java/JavaConfigurationBuilder.kt | 61 ------ .../analysis/test/api/jvm/java/JavaFileCreator.kt | 25 --- .../analysis/test/api/jvm/java/JavaTestData.kt | 54 ----- .../analysis/test/api/jvm/java/JavaTestDataFile.kt | 27 --- .../analysis/test/api/jvm/java/JavaTestProject.kt | 73 ------- .../jvm/kotlin/KotlinJvmConfigurationBuilder.kt | 56 ------ .../api/jvm/kotlin/KotlinJvmDependencyUtils.kt | 22 -- .../test/api/jvm/kotlin/KotlinJvmTestProject.kt | 93 --------- .../api/jvm/mixed/MixedJvmConfigurationBuilder.kt | 69 ------- .../test/api/jvm/mixed/MixedJvmTestData.kt | 47 ----- .../test/api/jvm/mixed/MixedJvmTestProject.kt | 80 -------- .../analysis/test/api/kotlin/KotlinTestData.kt | 48 ----- .../analysis/test/api/kotlin/KotlinTestDataFile.kt | 27 --- .../analysis/test/api/kotlin/KtFileCreator.kt | 32 --- .../api/kotlin/sample/KotlinSampleFileCreator.kt | 32 --- .../test/api/kotlin/sample/KotlinSampleTestData.kt | 44 ---- .../api/kotlin/sample/KotlinSampleTestDataFile.kt | 27 --- .../analysis/test/api/markdown/MarkdownTestData.kt | 40 ---- .../test/api/markdown/MarkdownTestDataFile.kt | 26 --- .../analysis/test/api/markdown/MdFileCreator.kt | 28 --- .../analysis/test/api/util/CollectionUtils.kt | 18 -- .../dokka/analysis/test/api/util/DslApiUtils.kt | 9 - .../dokka/analysis/test/api/util/FileUtils.kt | 41 ---- 33 files changed, 1973 deletions(-) delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestData.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestDataFile.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProject.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProjectFactory.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisContext.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfiguration.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationBuilder.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationMapper.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaConfigurationBuilder.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaFileCreator.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestData.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestDataFile.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestProject.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmConfigurationBuilder.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmDependencyUtils.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmTestProject.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/mixed/MixedJvmConfigurationBuilder.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/mixed/MixedJvmTestData.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/mixed/MixedJvmTestProject.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/kotlin/KotlinTestData.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/kotlin/KotlinTestDataFile.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/kotlin/KtFileCreator.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/kotlin/sample/KotlinSampleFileCreator.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/kotlin/sample/KotlinSampleTestData.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/kotlin/sample/KotlinSampleTestDataFile.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/markdown/MarkdownTestData.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/markdown/MarkdownTestDataFile.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/markdown/MdFileCreator.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/CollectionUtils.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/DslApiUtils.kt delete mode 100644 subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/FileUtils.kt (limited to 'subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org') diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestData.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestData.kt deleted file mode 100644 index 64bfd7a3..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestData.kt +++ /dev/null @@ -1,21 +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.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 -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestDataFile.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestDataFile.kt deleted file mode 100644 index 5b2233ba..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestDataFile.kt +++ /dev/null @@ -1,37 +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.test.api - -import org.jetbrains.dokka.analysis.test.api.util.AnalysisTestDslMarker - -/** - * 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 -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProject.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProject.kt deleted file mode 100644 index 9c0fa936..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProject.kt +++ /dev/null @@ -1,97 +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.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 = moduleAndPackageDocumentationReader.read(pckg) - * } - * ``` - */ -fun TestProject.useServices(block: TestAnalysisServices.(context: TestAnalysisContext) -> Unit) { - withTempDirectory { tempDirectory -> - val (services, context) = TestProjectAnalyzer.analyze(this, tempDirectory) - services.block(context) - } -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProjectFactory.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProjectFactory.kt deleted file mode 100644 index 81a20243..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProjectFactory.kt +++ /dev/null @@ -1,67 +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.test.api - -import org.jetbrains.dokka.analysis.test.api.jvm.java.JavaTestProject -import org.jetbrains.dokka.analysis.test.api.jvm.kotlin.KotlinJvmTestProject -import org.jetbrains.dokka.analysis.test.api.jvm.mixed.MixedJvmTestProject -import org.jetbrains.dokka.analysis.test.api.util.AnalysisTestDslMarker - -/** - * Creates a single-target Kotlin/JVM test project that only has Kotlin source code. - * - * See [javaTestProject] and [mixedJvmTestProject] if you want to check interoperability - * with other JVM languages. - * - * By default, the sources are put in `/src/main/kotlin`, and the JVM version of Kotlin's - * standard library is available on classpath. - * - * See [parse] and [useServices] functions to learn how to run Dokka with this project as input. - * - * @sample org.jetbrains.dokka.analysis.test.jvm.kotlin.SampleKotlinJvmAnalysisTest.sample - */ -fun kotlinJvmTestProject(init: (@AnalysisTestDslMarker KotlinJvmTestProject).() -> Unit): TestProject { - val testData = KotlinJvmTestProject() - testData.init() - return testData -} - -/** - * Creates a Java-only test project. - * - * This can be used to test Dokka's Java support or specific - * corner cases related to parsing Java sources. - * - * By default, the sources are put in `/src/main/java`. No Kotlin source code is allowed. - * - * See [parse] and [useServices] functions to learn how to run Dokka with this project as input. - * - * @sample org.jetbrains.dokka.analysis.test.jvm.java.SampleJavaAnalysisTest.sample - */ -fun javaTestProject(init: (@AnalysisTestDslMarker JavaTestProject).() -> Unit): TestProject { - val testData = JavaTestProject() - testData.init() - return testData -} - -/** - * Creates a project where a number of JVM language sources are allowed, - * like Java and Kotlin sources co-existing in the same source directory. - * - * This can be used to test interoperability between JVM languages. - * - * By default, this project consists of a single "jvm" source set, which has two source root directories: - * * `/src/main/kotlin` - * * `/src/main/java` - * - * See [parse] and [useServices] functions to learn how to run Dokka with this project as input. - * - * @sample org.jetbrains.dokka.analysis.test.jvm.mixed.SampleMixedJvmAnalysisTest.sample - */ -fun mixedJvmTestProject(init: (@AnalysisTestDslMarker MixedJvmTestProject).() -> Unit): TestProject { - val testProject = MixedJvmTestProject() - testProject.init() - return testProject -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisContext.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisContext.kt deleted file mode 100644 index de6efb1b..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisContext.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.test.api.analysis - -import org.jetbrains.dokka.DokkaConfiguration -import org.jetbrains.dokka.analysis.test.api.TestProject -import org.jetbrains.dokka.analysis.test.api.configuration.TestDokkaConfiguration -import org.jetbrains.dokka.model.DModule -import org.jetbrains.dokka.plugability.DokkaContext - -/** - * Context and data gathered during the analysis of a [TestProject]. - */ -class TestAnalysisContext( - - /** - * The actual [DokkaContext] that was used to run Dokka. - * - * Includes all plugins and classes available on classpath during the analysis. - */ - val context: DokkaContext, - - /** - * The actual [DokkaConfiguration] that was used to run Dokka. - * - * It was initially mapped from [TestDokkaConfiguration], and then added to by Dokka itself. - */ - val configuration: DokkaConfiguration, - - /** - * The entry point to the documentable model of the analyzed [TestProject]. - */ - val module: DModule -) diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt deleted file mode 100644 index ab70bbd4..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt +++ /dev/null @@ -1,20 +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.test.api.analysis - -import org.jetbrains.dokka.analysis.kotlin.KotlinAnalysisPlugin -import org.jetbrains.dokka.analysis.kotlin.internal.ModuleAndPackageDocumentationReader -import org.jetbrains.dokka.analysis.kotlin.internal.SampleProviderFactory - -/** - * Services exposed in [KotlinAnalysisPlugin] that are ready to be used. - * - * This class exists purely for convenience and to reduce boilerplate in tests. - * It is analogous to calling `context.plugin().querySingle { serviceName }`. - */ -class TestAnalysisServices( - val sampleProviderFactory: SampleProviderFactory, - val moduleAndPackageDocumentationReader: ModuleAndPackageDocumentationReader -) diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt deleted file mode 100644 index 1668b53f..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt +++ /dev/null @@ -1,223 +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.test.api.analysis - -import org.jetbrains.dokka.CoreExtensions -import org.jetbrains.dokka.DokkaConfiguration -import org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin -import org.jetbrains.dokka.analysis.test.api.TestDataFile -import org.jetbrains.dokka.analysis.test.api.TestProject -import org.jetbrains.dokka.analysis.test.api.configuration.toDokkaConfiguration -import org.jetbrains.dokka.analysis.test.api.parse -import org.jetbrains.dokka.analysis.test.api.useServices -import org.jetbrains.dokka.analysis.test.api.util.withTempDirectory -import org.jetbrains.dokka.model.DModule -import org.jetbrains.dokka.plugability.DokkaContext -import org.jetbrains.dokka.plugability.plugin -import org.jetbrains.dokka.plugability.querySingle -import org.jetbrains.dokka.transformers.documentation.DefaultDocumentableMerger -import org.jetbrains.dokka.transformers.documentation.DocumentableMerger -import org.jetbrains.dokka.transformers.sources.SourceToDocumentableTranslator -import org.jetbrains.dokka.utilities.DokkaConsoleLogger -import org.jetbrains.dokka.utilities.LoggingLevel -import java.io.File - -/** - * The main logger used for running Dokka and analyzing projects. - * - * Changing the level to [LoggingLevel.DEBUG] can help with debugging faulty tests - * or tricky corner cases. - */ -val analysisLogger = DokkaConsoleLogger(minLevel = LoggingLevel.INFO) - -/** - * Analyzer of the test projects, it is essentially a very simple Dokka runner. - * - * Takes all virtual files of the given [TestProject], creates the real files for - * them in a temporary directory, and then runs Dokka with this temporary directory - * as the input user project. This allows us to simulate Dokka's behavior and results - * on a made-up project as if it were real and run via the CLI runner. - * - * Executes only a limited number of steps and uses a small subset of [CoreExtensions] - * that are necessary to test the analysis logic. - * - * Works only with single-module projects, where the source code of this project - * resides in the root `src` directory. Works with multiple source sets and targets, - * so both simple Kotlin/JVM and more complicated Kotlin Multiplatform project must work. - */ -object TestProjectAnalyzer { - - /** - * A quick way to analyze a [TestProject], for cases when only the documentable - * model is needed to verify the result. - * - * Creates the input test files, runs Dokka and then deletes them right after the documentable - * model has been created, leaving no trailing files or any other garbage behind. - * - * @see [TestProject.parse] for a user-friendly way to call it - */ - fun parse(testProject: TestProject): DModule { - // since we only need documentables, we can delete the input test files right away - return withTempDirectory(analysisLogger) { tempDirectory -> - val (_, context) = testProject.initialize(outputDirectory = tempDirectory) - generateDocumentableModel(context) - } - } - - /** - * Works in the same way as [parse], but it returns the context and configuration used for - * running Dokka, and does not delete the input test files at the end of the execution - it - * must be taken care of on call site. - * - * @param persistentDirectory a directory that will be used to generate the input test files into. - * It must be available during the test run, especially if services are used, - * otherwise parts of Dokka might not work as expected. Can be safely deleted - * at the end of the test after all asserts have been run. - * - * @see [TestProject.useServices] for a user-friendly way to call it - */ - fun analyze( - testProject: TestProject, - persistentDirectory: File - ): Pair { - val (dokkaConfiguration, dokkaContext) = testProject.initialize(outputDirectory = persistentDirectory) - val analysisServices = createTestAnalysisServices(dokkaContext) - val testAnalysisContext = TestAnalysisContext( - context = dokkaContext, - configuration = dokkaConfiguration, - module = generateDocumentableModel(dokkaContext) - ) - return analysisServices to testAnalysisContext - } - - /** - * Prepares this [TestProject] for analysis by creating - * the test files, setting up context and configuration. - */ - private fun TestProject.initialize(outputDirectory: File): Pair { - analysisLogger.progress("Initializing and verifying project $this") - this.verify() - require(outputDirectory.isDirectory) { - "outputDirectory has to exist and be a directory: $outputDirectory" - } - this.initializeTestFiles(relativeToDir = outputDirectory) - - analysisLogger.progress("Creating configuration and context") - val testDokkaConfiguration = this.getConfiguration() - val dokkaConfiguration = testDokkaConfiguration.toDokkaConfiguration(projectDir = outputDirectory).also { - it.verify() - } - return dokkaConfiguration to createContext(dokkaConfiguration) - } - - /** - * Takes the virtual [TestDataFile] of this [TestProject] and creates - * the real files relative to the [relativeToDir] param. - */ - private fun TestProject.initializeTestFiles(relativeToDir: File) { - analysisLogger.progress("Initializing test files relative to the \"$relativeToDir\" directory") - - this.getTestData().getFiles().forEach { - val testDataFile = relativeToDir.resolve(it.pathFromProjectRoot.removePrefix("/")) - try { - testDataFile.parentFile.mkdirs() - } catch (e: Exception) { - // the IOException thrown from `mkdirs()` has no details and thus is more difficult to debug. - throw IllegalStateException("Unable to create dirs \"${testDataFile.parentFile}\"", e) - } - - analysisLogger.debug("Creating \"${testDataFile.absolutePath}\"") - check(testDataFile.createNewFile()) { - "Unable to create a test file: ${testDataFile.absolutePath}" - } - testDataFile.writeText(it.getContents(), Charsets.UTF_8) - } - } - - /** - * Verifies this [DokkaConfiguration] to make sure there are no unexpected - * parameter option values, such as non-existing classpath entries. - * - * If this method fails, it's likely there's a configuration error in the test, - * or an exception must be made in one of the checks. - */ - private fun DokkaConfiguration.verify() { - this.includes.forEach { verifyFileExists(it) } - this.sourceSets.forEach { sourceSet -> - sourceSet.classpath.forEach { verifyFileExists(it) } - sourceSet.includes.forEach { verifyFileExists(it) } - sourceSet.samples.forEach { verifyFileExists(it) } - // we do not verify sourceRoots since the source directory - // is not guaranteed to exist even if it was configured. - } - } - - private fun verifyFileExists(file: File) { - if (!file.exists() && !file.absolutePath.contains("non-existing")) { - throw IllegalArgumentException( - "The provided file does not exist. Bad test data or configuration? " + - "If it is done intentionally, add \"non-existing\" to the path or the name. File: \"$file\"" - ) - } - } - - private fun createContext(dokkaConfiguration: DokkaConfiguration): DokkaContext { - analysisLogger.progress("Creating DokkaContext from test configuration") - return DokkaContext.create( - configuration = dokkaConfiguration, - logger = analysisLogger, - pluginOverrides = listOf() - ) - } - - /** - * Generates the documentable model by using all available [SourceToDocumentableTranslator] extensions, - * and then merging all the results into a single [DModule] by calling [DocumentableMerger]. - */ - private fun generateDocumentableModel(context: DokkaContext): DModule { - analysisLogger.progress("Generating the documentable model") - val sourceSetModules = context - .configuration - .sourceSets - .map { sourceSet -> translateSources(sourceSet, context) } - .flatten() - - if (sourceSetModules.isEmpty()) { - throw IllegalStateException("Got no modules after translating sources. Is the test data set up?") - } - - return DefaultDocumentableMerger(context).invoke(sourceSetModules) - ?: error("Unable to merge documentables for some reason") - } - - /** - * Translates input source files to the documentable model by using - * all registered [SourceToDocumentableTranslator] core extensions. - */ - private fun translateSources(sourceSet: DokkaConfiguration.DokkaSourceSet, context: DokkaContext): List { - val translators = context[CoreExtensions.sourceToDocumentableTranslator] - require(translators.isNotEmpty()) { - "Need at least one source to documentable translator to run tests, otherwise no data will be generated." - } - analysisLogger.debug("Translating sources for ${sourceSet.sourceSetID}") - return translators.map { it.invoke(sourceSet, context) } - } - - /** - * A helper function to query analysis services, to avoid - * boilerplate and misconfiguration in the tests. - * - * The idea is to provide the users with ready-to-use services, - * without them having to know how to query or configure them. - */ - private fun createTestAnalysisServices(context: DokkaContext): TestAnalysisServices { - analysisLogger.progress("Creating analysis services") - val internalPlugin = context.plugin() - return TestAnalysisServices( - sampleProviderFactory = internalPlugin.querySingle { sampleProviderFactory }, - moduleAndPackageDocumentationReader = internalPlugin.querySingle { moduleAndPackageDocumentationReader } - ) - } -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfiguration.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfiguration.kt deleted file mode 100644 index 5c5a0daf..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfiguration.kt +++ /dev/null @@ -1,171 +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.test.api.configuration - -import org.jetbrains.dokka.DokkaConfiguration -import org.jetbrains.dokka.DokkaSourceSetID -import org.jetbrains.dokka.Platform -import org.jetbrains.dokka.analysis.test.api.TestProject - -/** - * Configuration options for [TestProject]. - * - * Represents a trimmed-down version of [DokkaConfiguration] that only - * exposes properties that can be used by Dokka's analysis implementations. - */ -data class TestDokkaConfiguration( - - /** - * Name of this [TestProject]. - * - * @see DokkaConfiguration.moduleName - */ - val moduleName: String, - - /** - * References Markdown files that contain documentation for this module and packages. - * - * Contains paths relative to the root of [TestProject], so it must begin with `/`. - * - * Example: `/docs/module.md` - * - * @see DokkaConfiguration.includes - * @see https://kotlinlang.org/docs/dokka-module-and-package-docs.html - */ - val includes: Set = emptySet(), - - /** - * A number of source directories and their configuration options that - * make up this project. - * - * A multiplatform Kotlin project will typically have multiple source sets - * for the supported platforms, whereas a single Kotlin/JVM project will have only one. - * - * @see TestDokkaSourceSet - */ - val sourceSets: Set - - -) { - override fun toString(): String { - return "TestDokkaConfiguration(moduleName='$moduleName', includes=$includes, sourceSets=$sourceSets)" - } -} - -/** - * Configuration options for a collection of source files for a specific platform. - * - * Represents a trimmed-down version of [DokkaConfiguration.DokkaSourceSet] that only - * exposes properties that can be used by Dokka's analysis implementations. - * - * @see https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets - */ -data class TestDokkaSourceSet ( - - /** - * @see DokkaConfiguration.DokkaSourceSet.analysisPlatform - */ - val analysisPlatform: Platform, - - /** - * A unique identifier of this source set in the scope of the project. - * - * It must be unique even if two source sets have the same name, - * the same platform or the same configuration. - * - * @see DokkaConfiguration.DokkaSourceSet.sourceSetID - */ - val sourceSetID: DokkaSourceSetID, - - /** - * A set of source set ids that this source set depends on. - * - * @see DokkaConfiguration.DokkaSourceSet.dependentSourceSets - */ - val dependentSourceSets: Set, - - /** - * A set of directories that contain the source files for this source set. - * - * A source set typically has only one source root directory, but there can be additional - * ones if the project has generated sources that reside separately, or if the `@sample` - * tag is used, and the samples reside in a different directory. - * - * Contains paths relative to the root of [TestProject], so it must begin with `/`. - * - * @see DokkaConfiguration.DokkaSourceSet.sourceRoots - */ - val sourceRoots: Set, - - /** - * A set of JARs to be used for analyzing sources. - * - * If this [TestProject] exposes types from external libraries, Dokka needs to know - * about these libraries so that it can generate correct signatures and documentation. - * - * Contains absolute paths, can be any file, even if it has nothing to do with unit - * tests or test project. - * - * @see DokkaConfiguration.DokkaSourceSet.classpath - */ - val classpath: Set, - - /** - * References Markdown files that contain documentation for this module and packages. - * - * Contains paths relative to the root of [TestProject], so it must begin with `/`. - * - * Example: `/docs/module.md` - * - * @see DokkaConfiguration.DokkaSourceSet.includes - * @see https://kotlinlang.org/docs/dokka-module-and-package-docs.html - */ - val includes: Set = emptySet(), - - /** - * A set of Kotlin files with functions that show how to use certain API. - * - * Contains paths relative to the root of [TestProject], so it must begin with `/`. - * - * Example: `/samples/collectionSamples.kt` - * - * @see DokkaConfiguration.DokkaSourceSet.samples - */ - val samples: Set = emptySet(), - - /** - * Compatibility mode for Kotlin language version X.Y. - * - * Example: `1.9` - * - * @see https://kotlinlang.org/docs/compatibility-modes.html - */ - val languageVersion: String? = null, - - /** - * Compatibility mode for Kotlin API version X.Y. - * - * Example: `1.9` - * - * @see https://kotlinlang.org/docs/compatibility-modes.html - */ - val apiVersion: String? = null, - - -) { - override fun toString(): String { - return "TestDokkaSourceSet(" + - "analysisPlatform=$analysisPlatform, " + - "sourceSetID=$sourceSetID, " + - "dependentSourceSets=$dependentSourceSets, " + - "sourceRoots=$sourceRoots, " + - "classpath=$classpath, " + - "includes=$includes, " + - "samples=$samples, " + - "languageVersion=$languageVersion, " + - "apiVersion=$apiVersion" + - ")" - } -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationBuilder.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationBuilder.kt deleted file mode 100644 index b6563fb7..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationBuilder.kt +++ /dev/null @@ -1,145 +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.test.api.configuration - -import org.jetbrains.dokka.analysis.test.api.TestProject -import org.jetbrains.dokka.analysis.test.api.util.AnalysisTestDslMarker - -/** - * A builder for [TestDokkaConfiguration] that contains base options. - * - * Implementations can override the properties to modify the resulting test - * data or prohibit setting certain properties. - */ -@AnalysisTestDslMarker -abstract class BaseTestDokkaConfigurationBuilder { - - /** - * @see TestDokkaConfiguration.moduleName - */ - abstract var moduleName: String - - - /** - * @see TestDokkaConfiguration.includes - */ - open var includes: Set = emptySet() - - /** - * Verifies that this source set configuration is valid. For example, - * it should check that all file paths are set in the expected format. - * - * Must be invoked manually as part of [TestProject.verify]. - */ - open fun verify() { - includes.forEach { - verifyFilePathStartsWithSlash("includes", it) - verifyFileExtension("includes", it, ".md") - } - } - - abstract fun build(): TestDokkaConfiguration - - override fun toString(): String { - return "BaseTestDokkaConfigurationBuilder(moduleName='$moduleName', includes=$includes)" - } -} - -/** - * A builder for [TestDokkaSourceSet] that contains base options. - * - * Implementations can override the properties to modify the resulting test - * data or prohibit setting certain properties. - */ -@AnalysisTestDslMarker -abstract class BaseTestDokkaSourceSetBuilder { - - /** - * Directories **additional** to the default source roots. - * - * @see TestDokkaSourceSet.sourceRoots - */ - open var additionalSourceRoots: Set = emptySet() - - /** - * JARs **additional** to the default classpath. - * - * @see TestDokkaSourceSet.classpath - */ - open var additionalClasspath: Set = emptySet() - - /** - * @see TestDokkaSourceSet.includes - */ - open var includes: Set = emptySet() - - /** - * @see TestDokkaSourceSet.samples - */ - open var samples: Set = emptySet() - - /** - * @see TestDokkaSourceSet.languageVersion - */ - open var languageVersion: String? = null - - /** - * @see TestDokkaSourceSet.apiVersion - */ - open var apiVersion: String? = null - - /** - * Verifies that this source set configuration is valid. For example, - * it should check that all file paths are set in the expected format. - * - * Must be invoked manually during the verification of the - * higher-level [BaseTestDokkaConfigurationBuilder.verify]. - */ - open fun verify() { - additionalSourceRoots.forEach { - verifyFilePathStartsWithSlash("additionalSourceRoots", it) - } - additionalClasspath.forEach { - // this check can be extended to accept .klib, .class or other files - // as the need for it arises, as long as Dokka supports it - verifyFileExtension("additionalClasspath", it, ".jar") - } - includes.forEach { - verifyFilePathStartsWithSlash("includes", it) - verifyFileExtension("includes", it, ".md") - } - samples.forEach { - verifyFilePathStartsWithSlash("samples", it) - verifyFileExtension("samples", it, ".kt") - } - } - - abstract fun build(): TestDokkaSourceSet - - override fun toString(): String { - return "BaseTestDokkaSourceSetBuilder(" + - "additionalSourceRoots=$additionalSourceRoots, " + - "additionalClasspath=$additionalClasspath, " + - "includes=$includes, " + - "samples=$samples, " + - "languageVersion=$languageVersion, " + - "apiVersion=$apiVersion" + - ")" - } -} - -internal fun verifyFilePathStartsWithSlash(propertyName: String, path: String) { - require(path.startsWith("/")) { - "Property $propertyName must contain paths relative to the root of the project. " + - "Please, prefix it with \"/\" for readability and consistency." - } -} - -internal fun verifyFileExtension(propertyName: String, filePath: String, expectedExtension: String) { - require(filePath.endsWith(expectedExtension)) { - "Property $propertyName only accepts files with \"$expectedExtension\" extension. " + - "Got: \"${filePath.substringAfterLast("/")}\"." - } -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationMapper.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationMapper.kt deleted file mode 100644 index f6356ab2..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationMapper.kt +++ /dev/null @@ -1,177 +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.test.api.configuration - -import org.jetbrains.dokka.DokkaConfiguration -import org.jetbrains.dokka.DokkaSourceSetID -import org.jetbrains.dokka.Platform -import org.jetbrains.dokka.analysis.test.api.util.mapToSet -import java.io.File - -/** - * Maps [TestDokkaConfiguration] to the actual [DokkaConfiguration] that will - * be used to run Dokka; The resulting configuration must be valid from Dokka's perspective. - * - * @receiver test configuration to map to the real one; all file paths must be relative to the - * root of the project. - * @param projectDir the actual project directory that will be used to create test files in; - * the path must be absolute and must exist. - */ -fun TestDokkaConfiguration.toDokkaConfiguration(projectDir: File): DokkaConfiguration { - require(projectDir.exists() && projectDir.isDirectory) { - "Expected the \"projectDir\" File param to exist and be a directory" - } - - val moduleName = this.moduleName - val includes = this.includes.mapToSet { it.relativeTo(projectDir) } - val sourceSets = this.sourceSets.map { it.toDokkaSourceSet(projectDir) } - - return object : DokkaConfiguration { - - /* - * NOTE: The getters need to return data that can be compared by value. - * This means you can't recreate lists of interfaces on every invocation - * as their equals will return false, leading to difficult to trace bugs, - * especially when it comes to `SourceSetDependent` - */ - - override val moduleName: String - get() = moduleName - - override val includes: Set - get() = includes - - override val sourceSets: List - get() = sourceSets - - /* - * The plugin API uses the properties below to initialize plugins found on classpath. - * They are not settable directly in analysis tests, but must not throw any exceptions. - */ - override val pluginsClasspath: List - get() = emptyList() - override val pluginsConfiguration: List - get() = emptyList() - - /* - * The properties below are not used by the analysis modules, - * and thus they don't need to be supported. - * - * If one of the properties below starts being used during - * analysis (i.e starts throwing an exception), a corresponding - * test property should be added along with the mapping. - */ - override val moduleVersion: String - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val outputDir: File - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val cacheRoot: File - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val offlineMode: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val failOnWarning: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val modules: List - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val delayTemplateSubstitution: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val suppressObviousFunctions: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val suppressInheritedMembers: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val finalizeCoroutines: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - } -} - -private fun TestDokkaSourceSet.toDokkaSourceSet(relativeToDir: File): DokkaConfiguration.DokkaSourceSet { - val analysisPlatform = this.analysisPlatform - val sourceSetID = this.sourceSetID - val dependentSourceSets = this.dependentSourceSets - val sourceRoots = this.sourceRoots.mapToSet { it.relativeTo(relativeToDir) } - val classpath = this.classpath.map { File(it) } - val includes = this.includes.mapToSet { it.relativeTo(relativeToDir) } - val samples = this.samples.mapToSet { it.relativeTo(relativeToDir) } - val languageVersion = this.languageVersion - val apiVersion = this.apiVersion - - return object : DokkaConfiguration.DokkaSourceSet { - - /* - * NOTE: The getters need to return data that can be compared by value. - * This means you can't recreate lists of interfaces on every invocation - * as their equals will return false, leading to difficult to trace bugs, - * especially when it comes to `SourceSetDependent` - */ - - override val analysisPlatform: Platform - get() = analysisPlatform - - override val sourceSetID: DokkaSourceSetID - get() = sourceSetID - - override val dependentSourceSets: Set - get() = dependentSourceSets - - override val sourceRoots: Set - get() = sourceRoots - - override val classpath: List - get() = classpath - - override val includes: Set - get() = includes - - override val samples: Set - get() = samples - - override val languageVersion: String? - get() = languageVersion - - override val apiVersion: String? - get() = apiVersion - - - /* - * The properties below are not used by the analysis modules, - * and thus they don't need to be supported. - * - * If one of the properties below starts being used during - * analysis (i.e starts throwing an exception), a corresponding - * test property should be added along with the mapping. - */ - override val displayName: String - get() = throw NotImplementedError("Not expected to be used by analysis modules") - @Suppress("OVERRIDE_DEPRECATION") - override val includeNonPublic: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val reportUndocumented: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val skipEmptyPackages: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val skipDeprecated: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val jdkVersion: Int - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val sourceLinks: Set - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val perPackageOptions: List - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val externalDocumentationLinks: Set - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val noStdlibLink: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val noJdkLink: Boolean - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val suppressedFiles: Set - get() = throw NotImplementedError("Not expected to be used by analysis modules") - override val documentedVisibilities: Set - get() = throw NotImplementedError("Not expected to be used by analysis modules") - } -} - -private fun String.relativeTo(dir: File): File { - return dir.resolve(this.removePrefix("/")) -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaConfigurationBuilder.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaConfigurationBuilder.kt deleted file mode 100644 index 6775fa21..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaConfigurationBuilder.kt +++ /dev/null @@ -1,61 +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.test.api.jvm.java - -import org.jetbrains.dokka.DokkaSourceSetID -import org.jetbrains.dokka.Platform -import org.jetbrains.dokka.analysis.test.api.configuration.BaseTestDokkaConfigurationBuilder -import org.jetbrains.dokka.analysis.test.api.configuration.BaseTestDokkaSourceSetBuilder -import org.jetbrains.dokka.analysis.test.api.configuration.TestDokkaConfiguration -import org.jetbrains.dokka.analysis.test.api.configuration.TestDokkaSourceSet -import org.jetbrains.dokka.analysis.test.api.util.AnalysisTestDslMarker - -/** - * An implementation of [BaseTestDokkaConfigurationBuilder] specific to [JavaTestProject]. - */ -class JavaTestConfigurationBuilder : BaseTestDokkaConfigurationBuilder() { - override var moduleName: String = "javaTestProject" - - private val javaSourceSetBuilder = JavaTestSourceSetBuilder() - - @AnalysisTestDslMarker - fun javaSourceSet(fillSourceSet: JavaTestSourceSetBuilder.() -> Unit) { - fillSourceSet(javaSourceSetBuilder) - } - - override fun verify() { - super.verify() - javaSourceSetBuilder.verify() - } - - override fun build(): TestDokkaConfiguration { - return TestDokkaConfiguration( - moduleName = moduleName, - includes = includes, - sourceSets = setOf(javaSourceSetBuilder.build()) - ) - } -} - -/** - * An implementation of [BaseTestDokkaSourceSetBuilder] specific to [JavaTestProject]. - * - * Defines sensible defaults that should cover the majority of simple projects. - */ -class JavaTestSourceSetBuilder : BaseTestDokkaSourceSetBuilder() { - override fun build(): TestDokkaSourceSet { - return TestDokkaSourceSet( - analysisPlatform = Platform.jvm, - sourceSetID = DokkaSourceSetID(scopeId = "project", sourceSetName = "java"), - dependentSourceSets = setOf(), - sourceRoots = additionalSourceRoots + setOf(JavaTestProject.DEFAULT_SOURCE_ROOT), - classpath = additionalClasspath, // TODO [beresnev] is kotlin jvm stdlib needed here? - includes = includes, - samples = samples, - languageVersion = languageVersion, - apiVersion = apiVersion - ) - } -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaFileCreator.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaFileCreator.kt deleted file mode 100644 index 2a79210f..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaFileCreator.kt +++ /dev/null @@ -1,25 +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.test.api.jvm.java - -/** - * Declares a capability that a `.java` file can be created in the scope of the implementation. - */ -interface JavaFileCreator { - - /** - * Creates a `.java` file. - * - * By default, the package of this file is deduced automatically from the [pathFromSrc] param. - * For example, for a path `org/jetbrains/dokka/test` the package will be `org.jetbrains.dokka.test`. - * It is normally prohibited for Java files to have a mismatch in package and file path, so it - * cannot be overridden. - * - * @param pathFromSrc path relative to the source code directory of the project. - * Must contain packages (if any) and end in `.java`. - * Example: `org/jetbrains/dokka/test/MyClass.java` - */ - fun javaFile(pathFromSrc: String, fillFile: JavaTestDataFile.() -> Unit) -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestData.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestData.kt deleted file mode 100644 index 48705e78..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestData.kt +++ /dev/null @@ -1,54 +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.test.api.jvm.java - -import org.jetbrains.dokka.analysis.test.api.TestData -import org.jetbrains.dokka.analysis.test.api.TestDataFile -import org.jetbrains.dokka.analysis.test.api.util.filePathToPackageName - -/** - * A container for populating and holding Java source code test data. - * - * This container exists so that common creation, population and verification logic - * can be reused, instead of having to implement [JavaFileCreator] multiple times. - * - * @param pathToJavaSources path to the `src` directory in which Java sources must reside. - * Must be relative to the root of the test project. Example: `/src/main/java` - * @see TestData - */ -class JavaTestData( - private val pathToJavaSources: String -) : TestData, JavaFileCreator { - - private val files = mutableListOf() - - override fun javaFile(pathFromSrc: String, fillFile: JavaTestDataFile.() -> Unit) { - val fileName = pathFromSrc.substringAfterLast("/") - check(fileName.endsWith(".java")) { "Java files are expected to have .java extension" } - - val testDataFile = JavaTestDataFile( - fullyQualifiedPackageName = filePathToPackageName(pathFromSrc), - pathFromProjectRoot = "$pathToJavaSources/$pathFromSrc", - ) - fillFile(testDataFile) - testDataFile.checkFileNameIsPresent(fileName) - files.add(testDataFile) - } - - private fun JavaTestDataFile.checkFileNameIsPresent(fileName: String) { - check(this.getContents().contains(fileName.removeSuffix(".java"))) { - "Expected the .java file name to be the same as the top-level declaration name (class/interface)." - } - } - - override fun getFiles(): List { - return files - } - - override fun toString(): String { - return "JavaTestData(pathToJavaSources='$pathToJavaSources', files=$files)" - } -} - diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestDataFile.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestDataFile.kt deleted file mode 100644 index d8cc86a8..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestDataFile.kt +++ /dev/null @@ -1,27 +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.test.api.jvm.java - -import org.jetbrains.dokka.analysis.test.api.TestDataFile - -class JavaTestDataFile( - fullyQualifiedPackageName: String, - pathFromProjectRoot: String, -) : TestDataFile(pathFromProjectRoot = pathFromProjectRoot) { - - private var fileContents = "package $fullyQualifiedPackageName;" + System.lineSeparator().repeat(2) - - operator fun String.unaryPlus() { - fileContents += (this.trimIndent() + System.lineSeparator()) - } - - override fun getContents(): String { - return fileContents - } - - override fun toString(): String { - return "JavaTestDataFile(pathFromProjectRoot='$pathFromProjectRoot', fileContents='$fileContents')" - } -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestProject.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestProject.kt deleted file mode 100644 index 39f0f0f6..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestProject.kt +++ /dev/null @@ -1,73 +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.test.api.jvm.java - -import org.jetbrains.dokka.analysis.test.api.TestData -import org.jetbrains.dokka.analysis.test.api.TestDataFile -import org.jetbrains.dokka.analysis.test.api.TestProject -import org.jetbrains.dokka.analysis.test.api.configuration.TestDokkaConfiguration -import org.jetbrains.dokka.analysis.test.api.javaTestProject -import org.jetbrains.dokka.analysis.test.api.markdown.MarkdownTestData -import org.jetbrains.dokka.analysis.test.api.markdown.MarkdownTestDataFile -import org.jetbrains.dokka.analysis.test.api.markdown.MdFileCreator -import org.jetbrains.dokka.analysis.test.api.util.AnalysisTestDslMarker -import org.jetbrains.dokka.analysis.test.api.util.flatListOf - -/** - * @see javaTestProject for an explanation and a convenient way to construct this project - */ -class JavaTestProject : TestProject, JavaFileCreator, MdFileCreator { - - private val projectConfigurationBuilder = JavaTestConfigurationBuilder() - - private val javaSourceSet = JavaTestData(pathToJavaSources = DEFAULT_SOURCE_ROOT) - private val markdownTestData = MarkdownTestData() - - @AnalysisTestDslMarker - fun dokkaConfiguration(fillConfiguration: JavaTestConfigurationBuilder.() -> Unit) { - fillConfiguration(projectConfigurationBuilder) - } - - @AnalysisTestDslMarker - override fun javaFile(pathFromSrc: String, fillFile: JavaTestDataFile.() -> Unit) { - javaSourceSet.javaFile(pathFromSrc, fillFile) - } - - @AnalysisTestDslMarker - override fun mdFile(pathFromProjectRoot: String, fillFile: MarkdownTestDataFile.() -> Unit) { - markdownTestData.mdFile(pathFromProjectRoot, fillFile) - } - - override fun verify() { - projectConfigurationBuilder.verify() - } - - override fun getConfiguration(): TestDokkaConfiguration { - return projectConfigurationBuilder.build() - } - - override fun getTestData(): TestData { - return object : TestData { - override fun getFiles(): List { - return flatListOf( - this@JavaTestProject.javaSourceSet.getFiles(), - this@JavaTestProject.markdownTestData.getFiles() - ) - } - } - } - - override fun toString(): String { - return "JavaTestProject(" + - "projectConfigurationBuilder=$projectConfigurationBuilder, " + - "javaSourceSet=$javaSourceSet, " + - "markdownTestData=$markdownTestData" + - ")" - } - - internal companion object { - internal const val DEFAULT_SOURCE_ROOT = "/src/main/java" - } -} diff --git a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmConfigurationBuilder.kt b/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmConfigurationBuilder.kt deleted file mode 100644 index a0255611..00000000 --- a/subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmConfigurationBuilder.kt +++ /dev/null @@ -1,56 +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.test.api.jvm.kotlin - -import org.jetbrains.dokka.DokkaSourceSetID -import org.jetbrains.dokka.Platform -import org.jetbrains.dokka.analysis.test.api.configuration.BaseTestDokkaConfigurationBuilder -import org.jetbrains.dokka.analysis.test.api.configuration.BaseTestDokkaSourceSetBuilder -import org.jetbrains.dokka.analysis.test.api.configuration.TestDokkaConfiguration -import org.jetbrains.dokka.analysis.test.api.configuration.TestDokkaSourceSet -import org.jetbrains.dokka.analysis.test.api.util.AnalysisTestDslMarker - -/** - * An implementation of [BaseTestDokkaConfigurationBuilder] specific to [KotlinJvmTestProject]. - */ -class KotlinJvmTestConfigurationBuilder : BaseTestDokkaConfigurationBuilder() { - override var moduleName: String = "kotlinJvmTestProject" - - private val kotlinSourceSetBuilder = KotlinJvmTestSourceSetBuilder() - - @AnalysisTestDslMarker - fun ko