diff options
8 files changed, 354 insertions, 86 deletions
diff --git a/core/src/main/kotlin/model/Documentable.kt b/core/src/main/kotlin/model/Documentable.kt index adc46d2a..293b8a30 100644 --- a/core/src/main/kotlin/model/Documentable.kt +++ b/core/src/main/kotlin/model/Documentable.kt @@ -87,10 +87,10 @@ sealed class DClasslike : Documentable(), WithScope, WithVisibility, WithExpectA data class DModule( override val name: String, - val packages: List<DPackage>, - override val documentation: SourceSetDependent<DocumentationNode>, + val packages: List<DPackage> = emptyList(), + override val documentation: SourceSetDependent<DocumentationNode> = emptyMap(), override val expectPresentInSet: DokkaSourceSet? = null, - override val sourceSets: Set<DokkaSourceSet>, + override val sourceSets: Set<DokkaSourceSet> = emptySet(), override val extra: PropertyContainer<DModule> = PropertyContainer.empty() ) : Documentable(), WithExtraProperties<DModule> { override val dri: DRI = DRI.topLevel @@ -102,13 +102,13 @@ data class DModule( data class DPackage( override val dri: DRI, - override val functions: List<DFunction>, - override val properties: List<DProperty>, - override val classlikes: List<DClasslike>, - val typealiases: List<DTypeAlias>, - override val documentation: SourceSetDependent<DocumentationNode>, + override val functions: List<DFunction> = emptyList(), + override val properties: List<DProperty> = emptyList(), + override val classlikes: List<DClasslike> = emptyList(), + val typealiases: List<DTypeAlias> = emptyList(), + override val documentation: SourceSetDependent<DocumentationNode> = emptyMap(), override val expectPresentInSet: DokkaSourceSet? = null, - override val sourceSets: Set<DokkaSourceSet>, + override val sourceSets: Set<DokkaSourceSet> = emptySet(), override val extra: PropertyContainer<DPackage> = PropertyContainer.empty() ) : Documentable(), WithScope, WithExtraProperties<DPackage> { override val name = dri.packageName.orEmpty() 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 e2720ff0..5bf7e52d 100644 --- a/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt +++ b/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt @@ -1,9 +1,12 @@ package testApi.testRunner -import com.intellij.openapi.application.PathManager import org.jetbrains.dokka.* +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.* +import org.jetbrains.dokka.model.doc.Description +import org.jetbrains.dokka.model.doc.DocumentationNode +import org.jetbrains.dokka.model.doc.Text import java.io.File -import java.net.URL fun dokkaConfiguration(block: TestDokkaConfigurationBuilder.() -> Unit): DokkaConfigurationImpl = TestDokkaConfigurationBuilder().apply(block).build() @@ -35,6 +38,10 @@ class TestDokkaConfigurationBuilder { fun sourceSets(block: SourceSetsBuilder.() -> Unit) { sourceSets.addAll(SourceSetsBuilder().apply(block)) } + + fun add(sourceSet: DokkaSourceSetImpl) { + sourceSets.add(sourceSet) + } } @DokkaConfigurationDsl @@ -43,6 +50,10 @@ class SourceSetsBuilder : ArrayList<DokkaSourceSetImpl>() { DokkaSourceSetBuilder().apply(block).build().apply(::add) } +fun sourceSet(block: DokkaSourceSetBuilder.() -> Unit): DokkaSourceSetImpl { + return DokkaSourceSetBuilder().apply(block).build() +} + @DokkaConfigurationDsl class DokkaSourceSetBuilder( var moduleName: String = "root", @@ -55,7 +66,6 @@ class DokkaSourceSetBuilder( var samples: List<String> = emptyList(), var includes: List<String> = emptyList(), var includeNonPublic: Boolean = false, - var includeRootPackage: Boolean = true, var reportUndocumented: Boolean = false, var skipEmptyPackages: Boolean = false, var skipDeprecated: Boolean = false, @@ -95,3 +105,41 @@ class DokkaSourceSetBuilder( analysisPlatform = Platform.fromString(analysisPlatform) ) } + +val defaultSourceSet = DokkaSourceSetImpl( + moduleDisplayName = "DEFAULT", + displayName = "DEFAULT", + sourceSetID = DokkaSourceSetID("DEFAULT", "DEFAULT"), + classpath = emptyList(), + sourceRoots = emptySet(), + dependentSourceSets = emptySet(), + samples = emptySet(), + includes = emptySet(), + includeNonPublic = false, + reportUndocumented = false, + skipEmptyPackages = true, + skipDeprecated = false, + jdkVersion = 8, + sourceLinks = emptySet(), + perPackageOptions = emptyList(), + externalDocumentationLinks = emptySet(), + languageVersion = null, + apiVersion = null, + noStdlibLink = false, + noJdkLink = false, + suppressedFiles = emptySet(), + analysisPlatform = Platform.DEFAULT +) + +// TODO NOW: Clean up +fun sourceSet(name: String): DokkaConfiguration.DokkaSourceSet { + return defaultSourceSet.copy( + displayName = name, + sourceSetID = defaultSourceSet.sourceSetID.copy(sourceSetName = name) + ) +} + +fun documentationNode(vararg texts: String): DocumentationNode { + return DocumentationNode(texts.toList().map { Description(Text(it)) }) +} + diff --git a/plugins/base/base-test-utils/src/main/kotlin/renderers/defaultSourceSet.kt b/plugins/base/base-test-utils/src/main/kotlin/renderers/defaultSourceSet.kt index a7a20f88..41ca7146 100644 --- a/plugins/base/base-test-utils/src/main/kotlin/renderers/defaultSourceSet.kt +++ b/plugins/base/base-test-utils/src/main/kotlin/renderers/defaultSourceSet.kt @@ -1,30 +1,3 @@ package renderers -import org.jetbrains.dokka.DokkaSourceSetID -import org.jetbrains.dokka.DokkaSourceSetImpl -import org.jetbrains.dokka.Platform - -val defaultSourceSet = DokkaSourceSetImpl( - moduleDisplayName = "DEFAULT", - displayName = "DEFAULT", - sourceSetID = DokkaSourceSetID("DEFAULT", "DEFAULT"), - classpath = emptyList(), - sourceRoots = emptySet(), - dependentSourceSets = emptySet(), - samples = emptySet(), - includes = emptySet(), - includeNonPublic = false, - reportUndocumented = false, - skipEmptyPackages = true, - skipDeprecated = false, - jdkVersion = 8, - sourceLinks = emptySet(), - perPackageOptions = emptyList(), - externalDocumentationLinks = emptySet(), - languageVersion = null, - apiVersion = null, - noStdlibLink = false, - noJdkLink = false, - suppressedFiles = emptySet(), - analysisPlatform = Platform.DEFAULT -) +val defaultSourceSet = testApi.testRunner.defaultSourceSet diff --git a/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationReader.kt b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationReader.kt index e8297f3f..4900e9a8 100644 --- a/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationReader.kt +++ b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationReader.kt @@ -21,7 +21,6 @@ internal interface ModuleAndPackageDocumentationReader { operator fun get(pkg: DPackage): SourceSetDependent<DocumentationNode> } -// TODO NOW: Test internal fun ModuleAndPackageDocumentationReader( context: DokkaContext, kotlinAnalysis: KotlinAnalysis? = null ): ModuleAndPackageDocumentationReader = ContextModuleAndPackageDocumentationReader(context, kotlinAnalysis) @@ -59,7 +58,11 @@ private class ContextModuleAndPackageDocumentationReader( override fun get(module: DModule): SourceSetDependent<DocumentationNode> { return findDocumentationNodes(module.sourceSets) { fragment -> - fragment.classifier == Classifier.Module && fragment.name == module.name + fragment.classifier == Classifier.Module && ( + /* Match fragment name against module name or distinct module displayName */ + fragment.name == module.name || + fragment.name == module.sourceSets.map { it.moduleDisplayName }.distinct().singleOrNull() + ) } } diff --git a/plugins/base/src/test/kotlin/transformers/AbstractContextModuleAndPackageDocumentationReaderTest.kt b/plugins/base/src/test/kotlin/transformers/AbstractContextModuleAndPackageDocumentationReaderTest.kt new file mode 100644 index 00000000..7f435013 --- /dev/null +++ b/plugins/base/src/test/kotlin/transformers/AbstractContextModuleAndPackageDocumentationReaderTest.kt @@ -0,0 +1,22 @@ +package transformers + +import org.jetbrains.dokka.model.SourceSetDependent +import org.jetbrains.dokka.model.doc.DocumentationNode +import org.jetbrains.dokka.model.doc.Text +import org.jetbrains.dokka.model.withDescendants +import org.junit.jupiter.api.io.TempDir +import java.nio.file.Path + +abstract class AbstractContextModuleAndPackageDocumentationReaderTest { + @TempDir + protected lateinit var temporaryDirectory: Path + + + protected val SourceSetDependent<DocumentationNode>.texts: List<String> + get() = values.flatMap { it.withDescendants() } + .flatMap { it.children } + .flatMap { it.children } + .mapNotNull { it as? Text } + .map { it.body } + +} diff --git a/plugins/base/src/test/kotlin/transformers/ContextModuleAndPackageDocumentationReaderTest1.kt b/plugins/base/src/test/kotlin/transformers/ContextModuleAndPackageDocumentationReaderTest1.kt new file mode 100644 index 00000000..e04e751c --- /dev/null +++ b/plugins/base/src/test/kotlin/transformers/ContextModuleAndPackageDocumentationReaderTest1.kt @@ -0,0 +1,188 @@ +package transformers + +import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet +import org.jetbrains.dokka.base.transformers.documentables.ModuleAndPackageDocumentationReader +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.DModule +import org.jetbrains.dokka.model.DPackage +import org.jetbrains.dokka.model.doc.DocumentationNode +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.testApi.logger.TestLogger +import org.jetbrains.dokka.utilities.DokkaConsoleLogger +import org.junit.jupiter.api.Assertions.assertEquals +import org.junit.jupiter.api.BeforeEach +import org.junit.jupiter.api.Test +import testApi.testRunner.dokkaConfiguration +import testApi.testRunner.sourceSet + +class ContextModuleAndPackageDocumentationReaderTest1 : AbstractContextModuleAndPackageDocumentationReaderTest() { + + + + private val includeSourceSetA by lazy { temporaryDirectory.resolve("includeA.md").toFile() } + private val includeSourceSetB by lazy { temporaryDirectory.resolve("includeB.md").toFile() } + + @BeforeEach + fun materializeIncludes() { + includeSourceSetA.writeText( + """ + # Module moduleA + This is moduleA + + # Package sample.a + This is package sample.a + + # Package noise.b + This will just add some noise + """.trimIndent() + ) + + includeSourceSetB.writeText( + """ + # Module moduleB + This is moduleB + + # Package sample.b + This is package sample.b + + # Package noise.b + This will just add some more noise + """.trimIndent() + ) + } + + private val sourceSetA by lazy { + sourceSet { + moduleName = "moduleA" + name = "sourceSetA" + includes = listOf(includeSourceSetA.canonicalPath) + } + } + + private val sourceSetB by lazy { + sourceSet { + moduleName = "moduleB" + name = "sourceSetB" + includes = listOf(includeSourceSetB.canonicalPath) + } + } + + private val sourceSetB2 by lazy { + sourceSet { + moduleName = "moduleB" + name = "sourceSetB2" + includes = emptyList() + } + } + + + private val context by lazy { + DokkaContext.create( + configuration = dokkaConfiguration { + sourceSets { + add(sourceSetA) + add(sourceSetB) + add(sourceSetB2) + } + }, + logger = TestLogger(DokkaConsoleLogger), + pluginOverrides = emptyList() + ) + } + + private val reader by lazy { ModuleAndPackageDocumentationReader(context) } + + @Test + fun `assert moduleA with sourceSetA`() { + val documentation = reader[DModule(name = "moduleA", sourceSets = setOf(sourceSetA))] + assertEquals( + 1, documentation.keys.size, + "Expected moduleA only containing documentation in a single source set" + ) + assertEquals( + "sourceSetA", documentation.keys.single().sourceSetID.sourceSetName, + "Expected moduleA documentation coming from sourceSetA" + ) + + assertEquals( + "This is moduleA", documentation.texts.single(), + "Expected moduleA documentation being present" + ) + } + + @Test + fun `assert moduleA with no source sets`() { + val documentation = reader[DModule("moduleA")] + assertEquals( + emptyMap<DokkaSourceSet, DocumentationNode>(), documentation, + "Expected no documentation received for module not declaring a matching sourceSet" + ) + } + + @Test + fun `assert moduleA with unknown source set`() { + val documentation = reader[DModule("moduleA", sourceSets = setOf(sourceSet { name = "unknown" }))] + assertEquals( + emptyMap<DokkaSourceSet, DocumentationNode>(), documentation, + "Expected no documentation received for module with unknown sourceSet" + ) + } + + @Test + fun `assert moduleA with all sourceSets`() { + val documentation = reader[DModule("moduleA", sourceSets = setOf(sourceSetA, sourceSetB, sourceSetB2))] + assertEquals(1, documentation.entries.size, "Expected only one entry from sourceSetA") + assertEquals(sourceSetA, documentation.keys.single(), "Expected only one entry from sourceSetA") + assertEquals("This is moduleA", documentation.texts.single()) + } + + @Test + fun `assert moduleB with sourceSetB and sourceSetB2`() { + val documentation = reader[DModule("moduleB", sourceSets = setOf(sourceSetB, sourceSetB2))] + assertEquals(1, documentation.keys.size, "Expected only one entry from sourceSetB") + assertEquals(sourceSetB, documentation.keys.single(), "Expected only one entry from sourceSetB") + assertEquals("This is moduleB", documentation.texts.single()) + } + + @Test + fun `assert sample_A in sourceSetA`() { + val documentation = reader[DPackage(DRI("sample.a"), sourceSets = setOf(sourceSetA))] + assertEquals(1, documentation.keys.size, "Expected only one entry from sourceSetA") + assertEquals(sourceSetA, documentation.keys.single(), "Expected only one entry from sourceSetA") + assertEquals("This is package sample.a", documentation.texts.single()) + } + + @Test + fun `assert sample_a_sub in sourceSetA`() { + val documentation = reader[DPackage(DRI("sample.a.sub"), sourceSets = setOf(sourceSetA))] + assertEquals( + emptyMap<DokkaSourceSet, DocumentationNode>(), documentation, + "Expected no documentation found for different package" + ) + } + + @Test + fun `assert sample_a in sourceSetB`() { + val documentation = reader[DPackage(DRI("sample.a"), sourceSets = setOf(sourceSetB))] + assertEquals( + emptyMap<DokkaSourceSet, DocumentationNode>(), documentation, + "Expected no documentation found for different sourceSet" + ) + } + + @Test + fun `assert sample_b in sourceSetB`() { + val documentation = reader[DPackage(DRI("sample.b"), sourceSets = setOf(sourceSetB))] + assertEquals(1, documentation.keys.size, "Expected only one entry from sourceSetB") + assertEquals(sourceSetB, documentation.keys.single(), "Expected only one entry from sourceSetB") + assertEquals("This is package sample.b", documentation.texts.single()) + } + + @Test + fun `assert sample_b in sourceSetB and sourceSetB2`() { + val documentation = reader[DPackage(DRI("sample.b"), sourceSets = setOf(sourceSetB, sourceSetB2))] + assertEquals(1, documentation.keys.size, "Expected only one entry from sourceSetB") + assertEquals(sourceSetB, documentation.keys.single(), "Expected only one entry from sourceSetB") + assertEquals("This is package sample.b", documentation.texts.single()) + } +} diff --git a/plugins/base/src/test/kotlin/transformers/ContextModuleAndPackageDocumentationReaderTest2.kt b/plugins/base/src/test/kotlin/transformers/ContextModuleAndPackageDocumentationReaderTest2.kt new file mode 100644 index 00000000..e209a170 --- /dev/null +++ b/plugins/base/src/test/kotlin/transformers/ContextModuleAndPackageDocumentationReaderTest2.kt @@ -0,0 +1,63 @@ +package transformers + +import org.jetbrains.dokka.base.transformers.documentables.ModuleAndPackageDocumentationReader +import org.jetbrains.dokka.model.DModule +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.utilities.DokkaConsoleLogger +import org.junit.jupiter.api.Assertions.* +import org.junit.jupiter.api.BeforeEach +import org.junit.jupiter.api.Test +import testApi.testRunner.dokkaConfiguration +import testApi.testRunner.sourceSet + + +class ContextModuleAndPackageDocumentationReaderTest2: AbstractContextModuleAndPackageDocumentationReaderTest() { + + private val include by lazy { temporaryDirectory.resolve("include.md").toFile() } + + @BeforeEach + fun materializeInclude() { + include.writeText( + """ + # Module MyModuleDisplayName + Matching: moduleDisplayName + + # Module myModuleName + Matching: moduleName + """.trimIndent() + ) + } + + private val sourceSet by lazy { + sourceSet { + moduleName = "myModuleName" + moduleDisplayName = "MyModuleDisplayName" + includes = listOf(include.canonicalPath) + } + } + + private val context by lazy { + DokkaContext.create( + configuration = dokkaConfiguration { + sourceSets { + add(sourceSet) + } + }, + logger = DokkaConsoleLogger, + pluginOverrides = emptyList() + ) + } + + private val reader by lazy { ModuleAndPackageDocumentationReader(context) } + + + @Test + fun `module matches for moduleName and moduleDisplayName`() { + val documentation = reader[DModule("myModuleName", sourceSets = setOf(sourceSet))] + assertEquals(1, documentation.keys.size, "Expected only one entry from sourceSet") + assertEquals(sourceSet, documentation.keys.single(), "Expected only one entry from sourceSet") + assertEquals( + listOf("Matching: moduleDisplayName", "Matching: moduleName"), documentation.texts + ) + } +} diff --git a/plugins/base/src/test/kotlin/transformers/ModuleAndPackageDocumentationTransformerTest.kt b/plugins/base/src/test/kotlin/transformers/ModuleAndPackageDocumentationTransformerTest.kt index a947633d..d2b41273 100644 --- a/plugins/base/src/test/kotlin/transformers/ModuleAndPackageDocumentationTransformerTest.kt +++ b/plugins/base/src/test/kotlin/transformers/ModuleAndPackageDocumentationTransformerTest.kt @@ -1,18 +1,16 @@ package transformers -import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet import org.jetbrains.dokka.base.transformers.documentables.ModuleAndPackageDocumentationReader import org.jetbrains.dokka.base.transformers.documentables.ModuleAndPackageDocumentationTransformer import org.jetbrains.dokka.links.DRI import org.jetbrains.dokka.model.DModule import org.jetbrains.dokka.model.DPackage import org.jetbrains.dokka.model.SourceSetDependent -import org.jetbrains.dokka.model.doc.Description import org.jetbrains.dokka.model.doc.DocumentationNode -import org.jetbrains.dokka.model.doc.Text import org.junit.jupiter.api.Assertions.assertEquals import org.junit.jupiter.api.Test -import renderers.defaultSourceSet +import testApi.testRunner.documentationNode +import testApi.testRunner.sourceSet class ModuleAndPackageDocumentationTransformerTest { @@ -141,22 +139,22 @@ class ModuleAndPackageDocumentationTransformerTest { documentation = emptyMap(), sourceSets = emptySet(), packages = listOf( - dPackage( - name = "com.sample", + DPackage( + dri = DRI("com.sample"), documentation = mapOf( sourceSet("A") to documentationNode("pre-existing:A:com.sample") ), sourceSets = setOf(sourceSet("A"), sourceSet("B"), sourceSet("C")), ), - dPackage( - name = "com.attach", + DPackage( + dri = DRI("com.attach"), documentation = mapOf( sourceSet("A") to documentationNode("pre-existing:A:com.attach") ), sourceSets = setOf(sourceSet("A"), sourceSet("B"), sourceSet("C")) ), - dPackage( - name = "com.attach.sub", + DPackage( + dri = DRI("com.attach.sub"), documentation = mapOf( sourceSet("A") to documentationNode("pre-existing:A:com.attach.sub"), sourceSet("B") to documentationNode("pre-existing:B:com.attach.sub"), @@ -178,7 +176,7 @@ class ModuleAndPackageDocumentationTransformerTest { val comSample = result.single().packages.single { it.dri.packageName == "com.sample" } assertEquals( - mapOf(sourceSet("A") to documentationNode("pre-existing:A:com.sample")), + mapOf(sourceSet("A") to documentationNode("pre-existing:A:com.sample")), comSample.documentation, "Expected no documentation added to package 'com.sample' because of wrong package" ) @@ -199,8 +197,8 @@ class ModuleAndPackageDocumentationTransformerTest { documentation = emptyMap(), sourceSets = emptySet(), packages = listOf( - dPackage( - name = "com.sample", + DPackage( + dri = DRI("com.sample"), documentation = mapOf( /* No documentation added, since in wrong package */ sourceSet("A") to documentationNode("pre-existing:A:com.sample") @@ -208,8 +206,8 @@ class ModuleAndPackageDocumentationTransformerTest { sourceSets = setOf(sourceSet("A"), sourceSet("B"), sourceSet("C")), ), - dPackage( - name = "com.attach", + DPackage( + dri = DRI("com.attach"), documentation = mapOf( /* Documentation added */ sourceSet("A") to documentationNode("pre-existing:A:com.attach", "doc:A:com.attach"), @@ -217,8 +215,8 @@ class ModuleAndPackageDocumentationTransformerTest { ), sourceSets = setOf(sourceSet("A"), sourceSet("B"), sourceSet("C")), ), - dPackage( - name = "com.attach.sub", + DPackage( + dri = DRI("com.attach.sub"), documentation = mapOf( /* Documentation added */ sourceSet("A") to documentationNode( @@ -241,30 +239,3 @@ class ModuleAndPackageDocumentationTransformerTest { } } - - -private fun sourceSet(name: String): DokkaSourceSet { - return defaultSourceSet.copy( - displayName = name, - sourceSetID = defaultSourceSet.sourceSetID.copy(sourceSetName = name) - ) -} - -private fun documentationNode(vararg texts: String): DocumentationNode { - return DocumentationNode(texts.toList().map { Description(Text(it)) }) -} - -private fun dPackage( - name: String, - documentation: SourceSetDependent<DocumentationNode>, - sourceSets: Set<DokkaSourceSet> -): DPackage = DPackage( - dri = DRI(name), - documentation = documentation, - sourceSets = sourceSets, - classlikes = emptyList(), - functions = emptyList(), - properties = emptyList(), - typealiases = emptyList() - -) |