diff options
Diffstat (limited to 'plugins/base')
2 files changed, 270 insertions, 1 deletions
diff --git a/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt index 9bdec75a..bf6579af 100644 --- a/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt +++ b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt @@ -5,7 +5,6 @@ import org.jetbrains.dokka.model.DModule import org.jetbrains.dokka.model.doc.DocumentationNode import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer -// TODO NOW: Test internal class ModuleAndPackageDocumentationTransformer( private val moduleAndPackageDocumentationReader: ModuleAndPackageDocumentationReader ) : PreMergeDocumentableTransformer { diff --git a/plugins/base/src/test/kotlin/transformers/ModuleAndPackageDocumentationTransformerTest.kt b/plugins/base/src/test/kotlin/transformers/ModuleAndPackageDocumentationTransformerTest.kt new file mode 100644 index 00000000..a947633d --- /dev/null +++ b/plugins/base/src/test/kotlin/transformers/ModuleAndPackageDocumentationTransformerTest.kt @@ -0,0 +1,270 @@ +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 + + +class ModuleAndPackageDocumentationTransformerTest { + + @Test + fun `empty list of modules`() { + val transformer = ModuleAndPackageDocumentationTransformer( + object : ModuleAndPackageDocumentationReader { + override fun get(module: DModule): SourceSetDependent<DocumentationNode> = throw NotImplementedError() + override fun get(pkg: DPackage): SourceSetDependent<DocumentationNode> = throw NotImplementedError() + } + ) + + assertEquals( + emptyList<DModule>(), transformer(emptyList()), + ) + } + + @Test + fun `single module documentation`() { + val transformer = ModuleAndPackageDocumentationTransformer( + object : ModuleAndPackageDocumentationReader { + override fun get(pkg: DPackage): SourceSetDependent<DocumentationNode> = throw NotImplementedError() + override fun get(module: DModule): SourceSetDependent<DocumentationNode> { + return module.sourceSets.associateWith { sourceSet -> + documentationNode("doc" + sourceSet.displayName) + } + } + + } + ) + + val result = transformer( + listOf( + DModule( + "ModuleName", + documentation = emptyMap(), + packages = emptyList(), + sourceSets = setOf( + sourceSet("A"), + sourceSet("B") + ) + ) + ) + ) + + assertEquals( + DModule( + "ModuleName", + documentation = mapOf( + sourceSet("A") to documentationNode("docA"), + sourceSet("B") to documentationNode("docB") + ), + sourceSets = setOf(sourceSet("A"), sourceSet("B")), + packages = emptyList() + ), + result.single() + ) + + } + + @Test + fun `merges with already existing module documentation`() { + val transformer = ModuleAndPackageDocumentationTransformer( + object : ModuleAndPackageDocumentationReader { + override fun get(pkg: DPackage): SourceSetDependent<DocumentationNode> = throw NotImplementedError() + override fun get(module: DModule): SourceSetDependent<DocumentationNode> { + /* Only add documentation for first source set */ + return module.sourceSets.take(1).associateWith { sourceSet -> + documentationNode("doc" + sourceSet.displayName) + } + } + } + ) + + val result = transformer( + listOf( + DModule( + "MyModule", + documentation = mapOf( + sourceSet("A") to documentationNode("pre-existing:A"), + sourceSet("B") to documentationNode("pre-existing:B") + ), + sourceSets = setOf(sourceSet("A"), sourceSet("B")), + packages = emptyList() + ) + ) + ) + + assertEquals( + DModule( + "MyModule", + documentation = mapOf( + /* Expect previous documentation and newly attached one */ + sourceSet("A") to documentationNode("pre-existing:A", "docA"), + /* Only first source set will get documentation attached */ + sourceSet("B") to documentationNode("pre-existing:B") + ), + sourceSets = setOf(sourceSet("A"), sourceSet("B")), + packages = emptyList() + ), + result.single() + ) + } + + @Test + fun `package documentation`() { + val transformer = ModuleAndPackageDocumentationTransformer( + object : ModuleAndPackageDocumentationReader { + override fun get(module: DModule): SourceSetDependent<DocumentationNode> = emptyMap() + override fun get(pkg: DPackage): SourceSetDependent<DocumentationNode> { + /* Only attach documentation to packages with 'attach' */ + if ("attach" !in pkg.dri.packageName.orEmpty()) return emptyMap() + /* Only attach documentation to two source sets */ + return pkg.sourceSets.take(2).associateWith { sourceSet -> + documentationNode("doc:${sourceSet.displayName}:${pkg.dri.packageName}") + } + } + } + ) + + val result = transformer( + listOf( + DModule( + "MyModule", + documentation = emptyMap(), + sourceSets = emptySet(), + packages = listOf( + dPackage( + name = "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", + documentation = mapOf( + sourceSet("A") to documentationNode("pre-existing:A:com.attach") + ), + sourceSets = setOf(sourceSet("A"), sourceSet("B"), sourceSet("C")) + ), + dPackage( + name = "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"), + sourceSet("C") to documentationNode("pre-existing:C:com.attach.sub") + ), + sourceSets = setOf(sourceSet("A"), sourceSet("B"), sourceSet("C")), + ) + ) + ) + ) + ) + + result.single().packages.forEach { pkg -> + assertEquals( + setOf(sourceSet("A"), sourceSet("B"), sourceSet("C")), pkg.sourceSets, + "Expected source sets A, B, C for package ${pkg.dri.packageName}" + ) + } + + val comSample = result.single().packages.single { it.dri.packageName == "com.sample" } + assertEquals( + mapOf(sourceSet("A") to documentationNode("pre-existing:A:com.sample")), + comSample.documentation, + "Expected no documentation added to package 'com.sample' because of wrong package" + ) + + val comAttach = result.single().packages.single { it.dri.packageName == "com.attach" } + assertEquals( + mapOf( + sourceSet("A") to documentationNode("pre-existing:A:com.attach", "doc:A:com.attach"), + sourceSet("B") to documentationNode("doc:B:com.attach") + ), + comAttach.documentation, + "Expected documentation added to source sets A and B" + ) + + assertEquals( + DModule( + "MyModule", + documentation = emptyMap(), + sourceSets = emptySet(), + packages = listOf( + dPackage( + name = "com.sample", + documentation = mapOf( + /* No documentation added, since in wrong package */ + sourceSet("A") to documentationNode("pre-existing:A:com.sample") + ), + sourceSets = setOf(sourceSet("A"), sourceSet("B"), sourceSet("C")), + + ), + dPackage( + name = "com.attach", + documentation = mapOf( + /* Documentation added */ + sourceSet("A") to documentationNode("pre-existing:A:com.attach", "doc:A:com.attach"), + sourceSet("B") to documentationNode("doc:B:com.attach") + ), + sourceSets = setOf(sourceSet("A"), sourceSet("B"), sourceSet("C")), + ), + dPackage( + name = "com.attach.sub", + documentation = mapOf( + /* Documentation added */ + sourceSet("A") to documentationNode( + "pre-existing:A:com.attach.sub", + "doc:A:com.attach.sub" + ), + /* Documentation added */ + sourceSet("B") to documentationNode( + "pre-existing:B:com.attach.sub", + "doc:B:com.attach.sub" + ), + /* No documentation added, since in wrong source set */ + sourceSet("C") to documentationNode("pre-existing:C:com.attach.sub") + ), + sourceSets = setOf(sourceSet("A"), sourceSet("B"), sourceSet("C")), + ) + ) + ), result.single() + ) + } + +} + + +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() + +) |