From 02f30b142aa467d3a24cc52a1fe3f2fed7ea1e33 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 31 Aug 2023 20:16:01 +0200 Subject: Enable explicit API mode (#3139) --- core/test-api/api/test-api.api | 3 +- .../src/main/kotlin/testApi/context/MockContext.kt | 5 +- .../src/main/kotlin/testApi/logger/TestLogger.kt | 12 +- .../testRunner/TestDokkaConfigurationBuilder.kt | 158 +++++++++++---------- .../main/kotlin/testApi/testRunner/TestRunner.kt | 41 +++--- 5 files changed, 113 insertions(+), 106 deletions(-) (limited to 'core/test-api') diff --git a/core/test-api/api/test-api.api b/core/test-api/api/test-api.api index 83335672..e0969258 100644 --- a/core/test-api/api/test-api.api +++ b/core/test-api/api/test-api.api @@ -3,8 +3,7 @@ public final class org/jetbrains/dokka/testApi/context/MockContext : org/jetbrai public synthetic fun ([Lkotlin/Pair;Lorg/jetbrains/dokka/DokkaConfiguration;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public fun get (Lorg/jetbrains/dokka/plugability/ExtensionPoint;)Ljava/util/List; public fun getConfiguration ()Lorg/jetbrains/dokka/DokkaConfiguration; - public fun getLogger ()Lorg/jetbrains/dokka/utilities/DokkaConsoleLogger; - public synthetic fun getLogger ()Lorg/jetbrains/dokka/utilities/DokkaLogger; + public fun getLogger ()Lorg/jetbrains/dokka/utilities/DokkaLogger; public fun getUnusedPoints ()Ljava/util/Collection; public fun plugin (Lkotlin/reflect/KClass;)Lorg/jetbrains/dokka/plugability/DokkaPlugin; public fun single (Lorg/jetbrains/dokka/plugability/ExtensionPoint;)Ljava/lang/Object; diff --git a/core/test-api/src/main/kotlin/testApi/context/MockContext.kt b/core/test-api/src/main/kotlin/testApi/context/MockContext.kt index 31d314de..06ea2dad 100644 --- a/core/test-api/src/main/kotlin/testApi/context/MockContext.kt +++ b/core/test-api/src/main/kotlin/testApi/context/MockContext.kt @@ -9,13 +9,14 @@ import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.plugability.DokkaPlugin import org.jetbrains.dokka.plugability.ExtensionPoint import org.jetbrains.dokka.utilities.DokkaConsoleLogger +import org.jetbrains.dokka.utilities.DokkaLogger import org.jetbrains.dokka.utilities.LoggingLevel import kotlin.reflect.KClass import kotlin.reflect.KMutableProperty import kotlin.reflect.full.memberProperties @Suppress("UNCHECKED_CAST") // It is only usable from tests so we do not care about safety -class MockContext( +public class MockContext( vararg extensions: Pair, (DokkaContext) -> Any>, private val testConfiguration: DokkaConfiguration? = null, private val unusedExtensionPoints: List>? = null @@ -36,7 +37,7 @@ class MockContext( override fun > single(point: E): T = get(point).single() - override val logger = DokkaConsoleLogger(LoggingLevel.DEBUG) + override val logger: DokkaLogger = DokkaConsoleLogger(LoggingLevel.DEBUG) override val configuration: DokkaConfiguration get() = testConfiguration ?: throw IllegalStateException("This mock context doesn't provide configuration") diff --git a/core/test-api/src/main/kotlin/testApi/logger/TestLogger.kt b/core/test-api/src/main/kotlin/testApi/logger/TestLogger.kt index 22059991..c285a663 100644 --- a/core/test-api/src/main/kotlin/testApi/logger/TestLogger.kt +++ b/core/test-api/src/main/kotlin/testApi/logger/TestLogger.kt @@ -10,24 +10,24 @@ import java.util.* /* * Even in tests it be used in a concurrent environment, so needs to be thread safe */ -class TestLogger(private val logger: DokkaLogger) : DokkaLogger { +public class TestLogger(private val logger: DokkaLogger) : DokkaLogger { override var warningsCount: Int by logger::warningsCount override var errorsCount: Int by logger::errorsCount private var _debugMessages = synchronizedMutableListOf() - val debugMessages: List get() = _debugMessages.toList() + public val debugMessages: List get() = _debugMessages.toList() private var _infoMessages = synchronizedMutableListOf() - val infoMessages: List get() = _infoMessages.toList() + public val infoMessages: List get() = _infoMessages.toList() private var _progressMessages = synchronizedMutableListOf() - val progressMessages: List get() = _progressMessages.toList() + public val progressMessages: List get() = _progressMessages.toList() private var _warnMessages = synchronizedMutableListOf() - val warnMessages: List get() = _warnMessages.toList() + public val warnMessages: List get() = _warnMessages.toList() private var _errorMessages = synchronizedMutableListOf() - val errorMessages: List get() = _errorMessages.toList() + public val errorMessages: List get() = _errorMessages.toList() override fun debug(message: String) { _debugMessages.add(message) diff --git a/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt b/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt index ccbede34..4c451fed 100644 --- a/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt +++ b/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt @@ -14,36 +14,37 @@ import org.jetbrains.dokka.model.doc.Text import org.jetbrains.dokka.model.properties.PropertyContainer import java.io.File -fun dokkaConfiguration(block: TestDokkaConfigurationBuilder.() -> Unit): DokkaConfigurationImpl = +public fun dokkaConfiguration(block: TestDokkaConfigurationBuilder.() -> Unit): DokkaConfigurationImpl = TestDokkaConfigurationBuilder().apply(block).build() @DslMarker -annotation class DokkaConfigurationDsl +public annotation class DokkaConfigurationDsl +// TODO this class heavily relies on `DokkaSourceSetImpl`, should be refactored to `DokkaSourceSet` @DokkaConfigurationDsl -class TestDokkaConfigurationBuilder { +public class TestDokkaConfigurationBuilder { - var moduleName: String = "root" + public var moduleName: String = "root" set(value) { check(lazySourceSets.isEmpty()) { "Cannot set moduleName after adding source sets" } field = value } - var moduleVersion: String = "1.0-SNAPSHOT" - var outputDir: File = File("out") - var format: String = "html" - var offlineMode: Boolean = false - var cacheRoot: String? = null - var pluginsClasspath: List = emptyList() - var pluginsConfigurations: MutableList = mutableListOf() - var failOnWarning: Boolean = false - var modules: List = emptyList() - var suppressObviousFunctions: Boolean = DokkaDefaults.suppressObviousFunctions - var includes: List = emptyList() - var suppressInheritedMembers: Boolean = DokkaDefaults.suppressInheritedMembers - var delayTemplateSubstitution: Boolean = DokkaDefaults.delayTemplateSubstitution + public var moduleVersion: String = "1.0-SNAPSHOT" + public var outputDir: File = File("out") + public var format: String = "html" + public var offlineMode: Boolean = false + public var cacheRoot: String? = null + public var pluginsClasspath: List = emptyList() + public var pluginsConfigurations: MutableList = mutableListOf() + public var failOnWarning: Boolean = false + public var modules: List = emptyList() + public var suppressObviousFunctions: Boolean = DokkaDefaults.suppressObviousFunctions + public var includes: List = emptyList() + public var suppressInheritedMembers: Boolean = DokkaDefaults.suppressInheritedMembers + public var delayTemplateSubstitution: Boolean = DokkaDefaults.delayTemplateSubstitution private val lazySourceSets = mutableListOf>() - fun build() = DokkaConfigurationImpl( + public fun build(): DokkaConfigurationImpl = DokkaConfigurationImpl( moduleName = moduleName, moduleVersion = moduleVersion, outputDir = outputDir, @@ -61,82 +62,87 @@ class TestDokkaConfigurationBuilder { finalizeCoroutines = false ) - fun sourceSets(block: SourceSetsBuilder.() -> Unit) { + public fun sourceSets(block: SourceSetsBuilder.() -> Unit) { lazySourceSets.addAll(SourceSetsBuilder(moduleName).apply(block)) } - fun sourceSet(block: DokkaSourceSetBuilder.() -> Unit): Lazy { + public fun sourceSet(block: DokkaSourceSetBuilder.() -> Unit): Lazy { val lazySourceSet = lazy { DokkaSourceSetBuilder(moduleName).apply(block).build() } lazySourceSets.add(lazySourceSet) return lazySourceSet } - fun unattachedSourceSet(block: DokkaSourceSetBuilder.() -> Unit): DokkaSourceSetImpl { + public fun unattachedSourceSet(block: DokkaSourceSetBuilder.() -> Unit): DokkaSourceSetImpl { return DokkaSourceSetBuilder(moduleName).apply(block).build() } } @DokkaConfigurationDsl -class SourceSetsBuilder(val moduleName: String) : ArrayList>() { - fun sourceSet(block: DokkaSourceSetBuilder.() -> Unit): Lazy = - lazy { DokkaSourceSetBuilder(moduleName).apply(block).build() }.apply(::add) +public class SourceSetsBuilder( + public val moduleName: String +) : ArrayList>() { + public fun sourceSet(block: DokkaSourceSetBuilder.() -> Unit): Lazy { + return lazy { DokkaSourceSetBuilder(moduleName).apply(block).build() }.apply(::add) + } } @DokkaConfigurationDsl -class DokkaSourceSetBuilder( +public class DokkaSourceSetBuilder( private val moduleName: String, - var name: String = "main", - var displayName: String = "JVM", - var classpath: List = emptyList(), - var sourceRoots: List = emptyList(), - var dependentSourceSets: Set = emptySet(), - var samples: List = emptyList(), - var includes: List = emptyList(), + public var name: String = "main", + public var displayName: String = "JVM", + public var classpath: List = emptyList(), + public var sourceRoots: List = emptyList(), + public var dependentSourceSets: Set = emptySet(), + public var samples: List = emptyList(), + public var includes: List = emptyList(), @Deprecated(message = "Use [documentedVisibilities] property for a more flexible control over documented visibilities") - var includeNonPublic: Boolean = false, - var documentedVisibilities: Set = DokkaDefaults.documentedVisibilities, - var reportUndocumented: Boolean = false, - var skipEmptyPackages: Boolean = false, - var skipDeprecated: Boolean = false, - var jdkVersion: Int = 8, - var languageVersion: String? = null, - var apiVersion: String? = null, - var noStdlibLink: Boolean = false, - var noJdkLink: Boolean = false, - var suppressedFiles: List = emptyList(), - var analysisPlatform: String = "jvm", - var perPackageOptions: List = emptyList(), - var externalDocumentationLinks: List = emptyList(), - var sourceLinks: List = emptyList() + public var includeNonPublic: Boolean = false, + public var documentedVisibilities: Set = DokkaDefaults.documentedVisibilities, + public var reportUndocumented: Boolean = false, + public var skipEmptyPackages: Boolean = false, + public var skipDeprecated: Boolean = false, + public var jdkVersion: Int = 8, + public var languageVersion: String? = null, + public var apiVersion: String? = null, + public var noStdlibLink: Boolean = false, + public var noJdkLink: Boolean = false, + public var suppressedFiles: List = emptyList(), + public var analysisPlatform: String = "jvm", + public var perPackageOptions: List = emptyList(), + public var externalDocumentationLinks: List = emptyList(), + public var sourceLinks: List = emptyList() ) { @Suppress("DEPRECATION") - fun build() = DokkaSourceSetImpl( - displayName = displayName, - sourceSetID = DokkaSourceSetID(moduleName, name), - classpath = classpath.map(::File), - sourceRoots = sourceRoots.map(::File).toSet(), - dependentSourceSets = dependentSourceSets, - samples = samples.map(::File).toSet(), - includes = includes.map(::File).toSet(), - includeNonPublic = includeNonPublic, - documentedVisibilities = documentedVisibilities, - reportUndocumented = reportUndocumented, - skipEmptyPackages = skipEmptyPackages, - skipDeprecated = skipDeprecated, - jdkVersion = jdkVersion, - sourceLinks = sourceLinks.toSet(), - perPackageOptions = perPackageOptions.toList(), - externalDocumentationLinks = externalDocumentationLinks.toSet(), - languageVersion = languageVersion, - apiVersion = apiVersion, - noStdlibLink = noStdlibLink, - noJdkLink = noJdkLink, - suppressedFiles = suppressedFiles.map(::File).toSet(), - analysisPlatform = Platform.fromString(analysisPlatform) - ) + public fun build(): DokkaSourceSetImpl { + return DokkaSourceSetImpl( + displayName = displayName, + sourceSetID = DokkaSourceSetID(moduleName, name), + classpath = classpath.map(::File), + sourceRoots = sourceRoots.map(::File).toSet(), + dependentSourceSets = dependentSourceSets, + samples = samples.map(::File).toSet(), + includes = includes.map(::File).toSet(), + includeNonPublic = includeNonPublic, + documentedVisibilities = documentedVisibilities, + reportUndocumented = reportUndocumented, + skipEmptyPackages = skipEmptyPackages, + skipDeprecated = skipDeprecated, + jdkVersion = jdkVersion, + sourceLinks = sourceLinks.toSet(), + perPackageOptions = perPackageOptions.toList(), + externalDocumentationLinks = externalDocumentationLinks.toSet(), + languageVersion = languageVersion, + apiVersion = apiVersion, + noStdlibLink = noStdlibLink, + noJdkLink = noJdkLink, + suppressedFiles = suppressedFiles.map(::File).toSet(), + analysisPlatform = Platform.fromString(analysisPlatform) + ) + } } -val defaultSourceSet = DokkaSourceSetImpl( +public val defaultSourceSet: DokkaSourceSetImpl = DokkaSourceSetImpl( displayName = "DEFAULT", sourceSetID = DokkaSourceSetID("DEFAULT", "DEFAULT"), classpath = emptyList(), @@ -161,14 +167,14 @@ val defaultSourceSet = DokkaSourceSetImpl( analysisPlatform = Platform.DEFAULT ) -fun sourceSet(name: String): DokkaConfiguration.DokkaSourceSet { +public fun sourceSet(name: String): DokkaConfiguration.DokkaSourceSet { return defaultSourceSet.copy( displayName = name, sourceSetID = defaultSourceSet.sourceSetID.copy(sourceSetName = name) ) } -fun dModule( +public fun dModule( name: String, packages: List = emptyList(), documentation: SourceSetDependent = emptyMap(), @@ -184,7 +190,7 @@ fun dModule( extra = extra ) -fun dPackage( +public fun dPackage( dri: DRI, functions: List = emptyList(), properties: List = emptyList(), @@ -206,7 +212,7 @@ fun dPackage( extra = extra ) -fun documentationNode(vararg texts: String): DocumentationNode { +public fun documentationNode(vararg texts: String): DocumentationNode { return DocumentationNode( texts.toList() .map { Description(CustomDocTag(listOf(Text(it)), name = "MARKDOWN_FILE")) }) diff --git a/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt b/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt index cdf74b02..23300190 100644 --- a/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt +++ b/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt @@ -23,14 +23,15 @@ import java.nio.file.Path import java.nio.file.Paths // TODO: take dokka configuration from file -abstract class AbstractTest, D : DokkaTestGenerator>( +public abstract class AbstractTest, D : DokkaTestGenerator>( protected val testBuilder: () -> T, protected val dokkaTestGenerator: (DokkaConfiguration, DokkaLogger, M, List) -> D, protected val logger: TestLogger, ) { - protected fun getTestDataDir(name: String) = - File("src/test/resources/$name").takeIf { it.exists() }?.toPath() + protected fun getTestDataDir(name: String): Path { + return File("src/test/resources/$name").takeIf { it.exists() }?.toPath() ?: throw InvalidPathException(name, "Cannot be found") + } /** * @param cleanupOutput if set to true, any temporary files will be cleaned up after execution. If set to false, @@ -198,38 +199,38 @@ abstract class AbstractTest, D : DokkaTestGe ?.replaceAfter(".jar", "") } - protected val stdlibExternalDocumentationLink = ExternalDocumentationLinkImpl( + protected val stdlibExternalDocumentationLink: ExternalDocumentationLinkImpl = ExternalDocumentationLinkImpl( URL("https://kotlinlang.org/api/latest/jvm/stdlib/"), URL("https://kotlinlang.org/api/latest/jvm/stdlib/package-list") ) - companion object { + public companion object { private val filePathRegex = Regex("""[\n^](\/[\w|\-]+)+(\.\w+)?\s*\n""") } } -interface TestMethods - -open class CoreTestMethods( - open val pluginsSetupStage: (DokkaContext) -> Unit, - open val verificationStage: (() -> Unit) -> Unit, - open val documentablesCreationStage: (List) -> Unit, - open val documentablesMergingStage: (DModule) -> Unit, - open val documentablesTransformationStage: (DModule) -> Unit, - open val pagesGenerationStage: (RootPageNode) -> Unit, - open val pagesTransformationStage: (RootPageNode) -> Unit, - open val renderingStage: (RootPageNode, DokkaContext) -> Unit, +public interface TestMethods + +public open class CoreTestMethods( + public open val pluginsSetupStage: (DokkaContext) -> Unit, + public open val verificationStage: (() -> Unit) -> Unit, + public open val documentablesCreationStage: (List) -> Unit, + public open val documentablesMergingStage: (DModule) -> Unit, + public open val documentablesTransformationStage: (DModule) -> Unit, + public open val pagesGenerationStage: (RootPageNode) -> Unit, + public open val pagesTransformationStage: (RootPageNode) -> Unit, + public open val renderingStage: (RootPageNode, DokkaContext) -> Unit, ) : TestMethods -abstract class TestBuilder { - abstract fun build(): M +public abstract class TestBuilder { + public abstract fun build(): M } -abstract class DokkaTestGenerator( +public abstract class DokkaTestGenerator( protected val configuration: DokkaConfiguration, protected val logger: DokkaLogger, protected val testMethods: T, protected val additionalPlugins: List = emptyList(), ) { - abstract fun generate() + public abstract fun generate() } -- cgit