From c01e49eec9558736959d12820361624a3c3e41e5 Mon Sep 17 00:00:00 2001 From: Marcin Aman Date: Mon, 1 Mar 2021 11:57:30 +0100 Subject: Suppress tag support (#1742) * Suppress tag support * Support Hide tag in javadoc * Extract hide tag to be in separate plugin --- .../kotlin/transformers/SuppressTagFilterTest.kt | 187 ++++++++++++++++++++ ...nfigurationDocumentableFilterTransformerTest.kt | 188 +++++++++++++++++++++ .../SuppressedDocumentableFilterTransformerTest.kt | 188 --------------------- 3 files changed, 375 insertions(+), 188 deletions(-) create mode 100644 plugins/base/src/test/kotlin/transformers/SuppressTagFilterTest.kt create mode 100644 plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt delete mode 100644 plugins/base/src/test/kotlin/transformers/SuppressedDocumentableFilterTransformerTest.kt (limited to 'plugins/base/src/test/kotlin') diff --git a/plugins/base/src/test/kotlin/transformers/SuppressTagFilterTest.kt b/plugins/base/src/test/kotlin/transformers/SuppressTagFilterTest.kt new file mode 100644 index 00000000..268f934d --- /dev/null +++ b/plugins/base/src/test/kotlin/transformers/SuppressTagFilterTest.kt @@ -0,0 +1,187 @@ +package transformers + +import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest +import org.jetbrains.dokka.model.DEnum +import org.jetbrains.dokka.model.WithCompanion +import org.junit.jupiter.api.Test +import kotlin.test.assertEquals +import kotlin.test.assertNotNull +import kotlin.test.assertNull + +class SuppressTagFilterTest : BaseAbstractTest() { + private val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src") + } + } + } + + @Test + fun `should filter classes with suppress tag`() { + testInline( + """ + |/src/suppressed/NotSuppressed.kt + |/** + | * sample docs + |*/ + |class NotSuppressed + |/src/suppressed/Suppressed.kt + |/** + | * sample docs + | * @suppress + |*/ + |class Suppressed + """.trimIndent(), configuration + ) { + documentablesFirstTransformationStep = { modules -> + assertEquals( + "NotSuppressed", + modules.flatMap { it.packages }.flatMap { it.classlikes }.singleOrNull()?.name + ) + } + } + } + + @Test + fun `should filter functions with suppress tag`() { + testInline( + """ + |/src/suppressed/Suppressed.kt + |class Suppressed { + | /** + | * sample docs + | * @suppress + | */ + | fun suppressedFun(){ } + |} + """.trimIndent(), configuration + ) { + documentablesFirstTransformationStep = { modules -> + assertNull(modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + .firstOrNull { it.name == "suppressedFun" }) + } + } + } + + @Test + fun `should filter top level functions`() { + testInline( + """ + |/src/suppressed/Suppressed.kt + |/** + | * sample docs + | * @suppress + | */ + |fun suppressedFun(){ } + | + |/** + | * Sample + | */ + |fun notSuppressedFun() { } + """.trimIndent(), configuration + ) { + documentablesFirstTransformationStep = { modules -> + assertNull(modules.flatMap { it.packages }.flatMap { it.functions } + .firstOrNull { it.name == "suppressedFun" }) + } + } + } + + @Test + fun `should filter top level type aliases`() { + testInline( + """ + |/src/suppressed/suppressed.kt + |/** + | * sample docs + | * @suppress + | */ + |typealias suppressedTypeAlias = String + | + |/** + | * Sample + | */ + |typealias notSuppressedTypeAlias = String + """.trimIndent(), configuration + ) { + documentablesFirstTransformationStep = { modules -> + assertNull(modules.flatMap { it.packages }.flatMap { it.typealiases } + .firstOrNull { it.name == "suppressedTypeAlias" }) + assertNotNull(modules.flatMap { it.packages }.flatMap { it.typealiases } + .firstOrNull { it.name == "notSuppressedTypeAlias" }) + } + } + } + + @Test + fun `should filter companion object`() { + testInline( + """ + |/src/suppressed/Suppressed.kt + |class Suppressed { + |/** + | * @suppress + | */ + |companion object { + | val x = 1 + |} + |} + """.trimIndent(), configuration + ) { + documentablesFirstTransformationStep = { modules -> + assertNull((modules.flatMap { it.packages }.flatMap { it.classlikes } + .firstOrNull { it.name == "Suppressed" } as? WithCompanion)?.companion) + } + } + } + + @Test + fun `should suppress inner classlike`() { + testInline( + """ + |/src/suppressed/Testing.kt + |class Testing { + | /** + | * Sample + | * @suppress + | */ + | inner class Suppressed { + | val x = 1 + | } + |} + """.trimIndent(), configuration + ) { + documentablesFirstTransformationStep = { modules -> + val testingClass = modules.flatMap { it.packages }.flatMap { it.classlikes }.single() + assertNull(testingClass.classlikes.firstOrNull()) + } + } + } + + @Test + fun `should suppress enum entry`() { + testInline( + """ + |/src/suppressed/Testing.kt + |enum class Testing { + | /** + | * Sample + | * @suppress + | */ + | SUPPRESSED, + | + | /** + | * Not suppressed + | */ + | NOT_SUPPRESSED + |} + """.trimIndent(), configuration + ) { + documentablesFirstTransformationStep = { modules -> + val testingClass = modules.flatMap { it.packages }.flatMap { it.classlikes }.single() as DEnum + assertEquals(listOf("NOT_SUPPRESSED"), testingClass.entries.map { it.name }) + } + } + } +} \ No newline at end of file diff --git a/plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt b/plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt new file mode 100644 index 00000000..c6d46b1f --- /dev/null +++ b/plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt @@ -0,0 +1,188 @@ +package transformers + +import org.jetbrains.dokka.PackageOptionsImpl +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest +import org.junit.jupiter.api.Assertions.assertEquals +import org.junit.jupiter.api.Assertions.assertIterableEquals +import org.junit.jupiter.api.Test + +class SuppressedByConfigurationDocumentableFilterTransformerTest : BaseAbstractTest() { + + @Test + fun `class filtered by package options`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src") + perPackageOptions = listOf( + packageOptions(matchingRegex = "suppressed.*", suppress = true), + packageOptions(matchingRegex = "default.*", suppress = false) + ) + } + } + } + + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + class Suppressed + + /src/default/Default.kt + package default + class Default.kt + """.trimIndent(), + configuration + ) { + documentablesMergingStage = { module -> + assertEquals(1, module.children.size, "Expected just a single package in module") + assertEquals(1, module.packages.size, "Expected just a single package in module") + + val pkg = module.packages.single() + assertEquals("default", pkg.dri.packageName, "Expected 'default' package in module") + assertEquals(1, pkg.children.size, "Expected just a single child in 'default' package") + assertEquals(1, pkg.classlikes.size, "Expected just a single child in 'default' package") + + val classlike = pkg.classlikes.single() + assertEquals(DRI("default", "Default"), classlike.dri, "Expected 'Default' class in 'default' package") + } + } + } + + @Test + fun `class filtered by more specific package options`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src") + perPackageOptions = listOf( + packageOptions(matchingRegex = "parent.some.*", suppress = false), + packageOptions(matchingRegex = "parent.some.suppressed.*", suppress = true), + + packageOptions(matchingRegex = "parent.other.*", suppress = true), + packageOptions(matchingRegex = "parent.other.default.*", suppress = false) + ) + } + } + } + + testInline( + """ + /src/parent/some/Some.kt + package parent.some + class Some + + /src/parent/some/suppressed/Suppressed.kt + package parent.some.suppressed + class Suppressed + + /src/parent/other/Other.kt + package parent.other + class Other + + /src/parent/other/default/Default.kt + package parent.other.default + class Default + """.trimIndent(), + configuration + ) { + documentablesMergingStage = { module -> + assertEquals(2, module.packages.size, "Expected two packages in module") + assertIterableEquals( + listOf(DRI("parent.some"), DRI("parent.other.default")).sortedBy { it.packageName }, + module.packages.map { it.dri }.sortedBy { it.packageName }, + "Expected 'parent.some' and 'parent.other.default' packages to be not suppressed" + ) + } + } + } + + @Test + fun `class filtered by parent file path`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src") + suppressedFiles = listOf("src/suppressed") + } + } + } + + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + class Suppressed + + /src/default/Default.kt + package default + class Default.kt + """.trimIndent(), + configuration + ) { + documentablesMergingStage = { module -> + assertEquals(1, module.children.size, "Expected just a single package in module") + assertEquals(1, module.packages.size, "Expected just a single package in module") + + val pkg = module.packages.single() + assertEquals("default", pkg.dri.packageName, "Expected 'default' package in module") + assertEquals(1, pkg.children.size, "Expected just a single child in 'default' package") + assertEquals(1, pkg.classlikes.size, "Expected just a single child in 'default' package") + + val classlike = pkg.classlikes.single() + assertEquals(DRI("default", "Default"), classlike.dri, "Expected 'Default' class in 'default' package") + } + } + } + + @Test + fun `class filtered by exact file path`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src") + suppressedFiles = listOf("src/suppressed/Suppressed.kt") + } + } + } + + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + class Suppressed + + /src/default/Default.kt + package default + class Default.kt + """.trimIndent(), + configuration + ) { + documentablesMergingStage = { module -> + assertEquals(1, module.children.size, "Expected just a single package in module") + assertEquals(1, module.packages.size, "Expected just a single package in module") + + val pkg = module.packages.single() + assertEquals("default", pkg.dri.packageName, "Expected 'default' package in module") + assertEquals(1, pkg.children.size, "Expected just a single child in 'default' package") + assertEquals(1, pkg.classlikes.size, "Expected just a single child in 'default' package") + + val classlike = pkg.classlikes.single() + assertEquals(DRI("default", "Default"), classlike.dri, "Expected 'Default' class in 'default' package") + } + } + } + + private fun packageOptions( + matchingRegex: String, + suppress: Boolean + ) = PackageOptionsImpl( + matchingRegex = matchingRegex, + suppress = suppress, + includeNonPublic = true, + reportUndocumented = false, + skipDeprecated = false + ) + +} diff --git a/plugins/base/src/test/kotlin/transformers/SuppressedDocumentableFilterTransformerTest.kt b/plugins/base/src/test/kotlin/transformers/SuppressedDocumentableFilterTransformerTest.kt deleted file mode 100644 index a022458a..00000000 --- a/plugins/base/src/test/kotlin/transformers/SuppressedDocumentableFilterTransformerTest.kt +++ /dev/null @@ -1,188 +0,0 @@ -package transformers - -import org.jetbrains.dokka.PackageOptionsImpl -import org.jetbrains.dokka.links.DRI -import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest -import org.junit.jupiter.api.Assertions.assertEquals -import org.junit.jupiter.api.Assertions.assertIterableEquals -import org.junit.jupiter.api.Test - -class SuppressedDocumentableFilterTransformerTest : BaseAbstractTest() { - - @Test - fun `class filtered by package options`() { - val configuration = dokkaConfiguration { - sourceSets { - sourceSet { - sourceRoots = listOf("src") - perPackageOptions = listOf( - packageOptions(matchingRegex = "suppressed.*", suppress = true), - packageOptions(matchingRegex = "default.*", suppress = false) - ) - } - } - } - - testInline( - """ - /src/suppressed/Suppressed.kt - package suppressed - class Suppressed - - /src/default/Default.kt - package default - class Default.kt - """.trimIndent(), - configuration - ) { - documentablesMergingStage = { module -> - assertEquals(1, module.children.size, "Expected just a single package in module") - assertEquals(1, module.packages.size, "Expected just a single package in module") - - val pkg = module.packages.single() - assertEquals("default", pkg.dri.packageName, "Expected 'default' package in module") - assertEquals(1, pkg.children.size, "Expected just a single child in 'default' package") - assertEquals(1, pkg.classlikes.size, "Expected just a single child in 'default' package") - - val classlike = pkg.classlikes.single() - assertEquals(DRI("default", "Default"), classlike.dri, "Expected 'Default' class in 'default' package") - } - } - } - - @Test - fun `class filtered by more specific package options`() { - val configuration = dokkaConfiguration { - sourceSets { - sourceSet { - sourceRoots = listOf("src") - perPackageOptions = listOf( - packageOptions(matchingRegex = "parent.some.*", suppress = false), - packageOptions(matchingRegex = "parent.some.suppressed.*", suppress = true), - - packageOptions(matchingRegex = "parent.other.*", suppress = true), - packageOptions(matchingRegex = "parent.other.default.*", suppress = false) - ) - } - } - } - - testInline( - """ - /src/parent/some/Some.kt - package parent.some - class Some - - /src/parent/some/suppressed/Suppressed.kt - package parent.some.suppressed - class Suppressed - - /src/parent/other/Other.kt - package parent.other - class Other - - /src/parent/other/default/Default.kt - package parent.other.default - class Default - """.trimIndent(), - configuration - ) { - documentablesMergingStage = { module -> - assertEquals(2, module.packages.size, "Expected two packages in module") - assertIterableEquals( - listOf(DRI("parent.some"), DRI("parent.other.default")).sortedBy { it.packageName }, - module.packages.map { it.dri }.sortedBy { it.packageName }, - "Expected 'parent.some' and 'parent.other.default' packages to be not suppressed" - ) - } - } - } - - @Test - fun `class filtered by parent file path`() { - val configuration = dokkaConfiguration { - sourceSets { - sourceSet { - sourceRoots = listOf("src") - suppressedFiles = listOf("src/suppressed") - } - } - } - - testInline( - """ - /src/suppressed/Suppressed.kt - package suppressed - class Suppressed - - /src/default/Default.kt - package default - class Default.kt - """.trimIndent(), - configuration - ) { - documentablesMergingStage = { module -> - assertEquals(1, module.children.size, "Expected just a single package in module") - assertEquals(1, module.packages.size, "Expected just a single package in module") - - val pkg = module.packages.single() - assertEquals("default", pkg.dri.packageName, "Expected 'default' package in module") - assertEquals(1, pkg.children.size, "Expected just a single child in 'default' package") - assertEquals(1, pkg.classlikes.size, "Expected just a single child in 'default' package") - - val classlike = pkg.classlikes.single() - assertEquals(DRI("default", "Default"), classlike.dri, "Expected 'Default' class in 'default' package") - } - } - } - - @Test - fun `class filtered by exact file path`() { - val configuration = dokkaConfiguration { - sourceSets { - sourceSet { - sourceRoots = listOf("src") - suppressedFiles = listOf("src/suppressed/Suppressed.kt") - } - } - } - - testInline( - """ - /src/suppressed/Suppressed.kt - package suppressed - class Suppressed - - /src/default/Default.kt - package default - class Default.kt - """.trimIndent(), - configuration - ) { - documentablesMergingStage = { module -> - assertEquals(1, module.children.size, "Expected just a single package in module") - assertEquals(1, module.packages.size, "Expected just a single package in module") - - val pkg = module.packages.single() - assertEquals("default", pkg.dri.packageName, "Expected 'default' package in module") - assertEquals(1, pkg.children.size, "Expected just a single child in 'default' package") - assertEquals(1, pkg.classlikes.size, "Expected just a single child in 'default' package") - - val classlike = pkg.classlikes.single() - assertEquals(DRI("default", "Default"), classlike.dri, "Expected 'Default' class in 'default' package") - } - } - } - - private fun packageOptions( - matchingRegex: String, - suppress: Boolean - ) = PackageOptionsImpl( - matchingRegex = matchingRegex, - suppress = suppress, - includeNonPublic = true, - reportUndocumented = false, - skipDeprecated = false - ) - -} -- cgit