From 5afe512c669e68aea3712ac37b67d005657cf60a Mon Sep 17 00:00:00 2001 From: Marcin Aman Date: Tue, 6 Apr 2021 18:06:42 +0200 Subject: Suppress inherited members (#1814) --- plugins/base/src/main/kotlin/DokkaBase.kt | 11 +- ...nheritedEntriesDocumentableFilterTransformer.kt | 13 ++ ...itedEntriesDocumentableFilterTransfromerTest.kt | 112 ++++++++++ ...sAndInheritedFunctionsDocumentableFilterTest.kt | 225 +++++++++++++++++++++ .../ObviousFunctionsDocumentableFilterTest.kt | 184 ----------------- 5 files changed, 357 insertions(+), 188 deletions(-) create mode 100644 plugins/base/src/main/kotlin/transformers/documentables/InheritedEntriesDocumentableFilterTransformer.kt create mode 100644 plugins/base/src/test/kotlin/transformers/InheritedEntriesDocumentableFilterTransfromerTest.kt create mode 100644 plugins/base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt delete mode 100644 plugins/base/src/test/kotlin/transformers/ObviousFunctionsDocumentableFilterTest.kt (limited to 'plugins/base/src') diff --git a/plugins/base/src/main/kotlin/DokkaBase.kt b/plugins/base/src/main/kotlin/DokkaBase.kt index d84207a5..0a18c3b1 100644 --- a/plugins/base/src/main/kotlin/DokkaBase.kt +++ b/plugins/base/src/main/kotlin/DokkaBase.kt @@ -82,6 +82,10 @@ class DokkaBase : DokkaPlugin() { preMergeDocumentableTransformer providing ::ObviousFunctionsDocumentableFilterTransformer } + val inheritedEntriesVisbilityFilter by extending { + preMergeDocumentableTransformer providing ::InheritedEntriesDocumentableFilterTransformer + } + val emptyPackagesFilter by extending { preMergeDocumentableTransformer providing ::EmptyPackagesFilterTransformer order { after( @@ -89,7 +93,8 @@ class DokkaBase : DokkaPlugin() { suppressedDocumentableFilter, documentableVisibilityFilter, suppressedBySuppressTagDocumentableFilter, - obviousFunctionsVisbilityFilter + obviousFunctionsVisbilityFilter, + inheritedEntriesVisbilityFilter, ) } } @@ -120,7 +125,6 @@ class DokkaBase : DokkaPlugin() { CoreExtensions.documentableTransformer with InheritorsExtractorTransformer() } - val undocumentedCodeReporter by extending { CoreExtensions.documentableTransformer with ReportUndocumentedTransformer() } @@ -163,7 +167,6 @@ class DokkaBase : DokkaPlugin() { CoreExtensions.renderer providing ::HtmlRenderer } - val defaultKotlinAnalysis by extending { kotlinAnalysis providing { ctx -> KotlinAnalysis(ctx.configuration.sourceSets, ctx.logger) } } @@ -246,4 +249,4 @@ class DokkaBase : DokkaPlugin() { val baseSearchbarDataInstaller by extending { htmlPreprocessors providing ::SearchbarDataInstaller order { after(sourceLinksTransformer) } } -} \ No newline at end of file +} diff --git a/plugins/base/src/main/kotlin/transformers/documentables/InheritedEntriesDocumentableFilterTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/InheritedEntriesDocumentableFilterTransformer.kt new file mode 100644 index 00000000..a1b5052d --- /dev/null +++ b/plugins/base/src/main/kotlin/transformers/documentables/InheritedEntriesDocumentableFilterTransformer.kt @@ -0,0 +1,13 @@ +package org.jetbrains.dokka.base.transformers.documentables + +import org.jetbrains.dokka.model.* +import org.jetbrains.dokka.model.properties.WithExtraProperties +import org.jetbrains.dokka.plugability.DokkaContext + +class InheritedEntriesDocumentableFilterTransformer(context: DokkaContext) : + SuppressedByConditionDocumentableFilterTransformer(context) { + override fun shouldBeSuppressed(d: Documentable): Boolean = + context.configuration.suppressInheritedMembers && (d as? WithExtraProperties)?.extra?.get( + InheritedMember + )?.inheritedFrom?.any { entry -> entry.value != null } ?: false +} \ No newline at end of file diff --git a/plugins/base/src/test/kotlin/transformers/InheritedEntriesDocumentableFilterTransfromerTest.kt b/plugins/base/src/test/kotlin/transformers/InheritedEntriesDocumentableFilterTransfromerTest.kt new file mode 100644 index 00000000..9cb956ba --- /dev/null +++ b/plugins/base/src/test/kotlin/transformers/InheritedEntriesDocumentableFilterTransfromerTest.kt @@ -0,0 +1,112 @@ +package transformers + +import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest +import org.junit.jupiter.api.Test +import kotlin.test.assertEquals + +class InheritedEntriesDocumentableFilterTransformerTest : BaseAbstractTest() { + val suppressingInheritedConfiguration = dokkaConfiguration { + suppressInheritedMembers = true + suppressObviousFunctions = false + sourceSets { + sourceSet { + sourceRoots = listOf("src") + } + } + } + + val nonSuppressingInheritedConfiguration = dokkaConfiguration { + suppressObviousFunctions = false + suppressInheritedMembers = false + sourceSets { + sourceSet { + sourceRoots = listOf("src") + } + } + } + + + @Test + fun `should suppress toString, equals and hashcode but keep custom ones`() { + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + data class Suppressed(val x: String) { + override fun toString(): String { + return "custom" + } + } + """.trimIndent(), + suppressingInheritedConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + assertEquals(listOf("toString", "copy", "component1").sorted(), functions.map { it.name }.sorted()) + } + } + } + + @Test + fun `should suppress toString, equals and hashcode`() { + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + data class Suppressed(val x: String) + """.trimIndent(), + suppressingInheritedConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + assertEquals(listOf("copy", "component1").sorted(), functions.map { it.name }.sorted()) + } + } + } + + @Test + fun `should also suppress properites`(){ + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + open class Parent { + val parentValue = "String" + } + + class Child : Parent { + + } + """.trimIndent(), + suppressingInheritedConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val properties = modules.flatMap { it.packages }.flatMap { it.classlikes }.first { it.name == "Child" }.properties + assertEquals(0, properties.size) + } + } + } + + @Test + fun `should not suppress properites if config says so`(){ + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + open class Parent { + val parentValue = "String" + } + + class Child : Parent { + + } + """.trimIndent(), + nonSuppressingInheritedConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val properties = modules.flatMap { it.packages }.flatMap { it.classlikes }.first { it.name == "Child" }.properties + assertEquals(listOf("parentValue"), properties.map { it.name }) + } + } + } +} \ No newline at end of file diff --git a/plugins/base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt b/plugins/base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt new file mode 100644 index 00000000..3618c8fb --- /dev/null +++ b/plugins/base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt @@ -0,0 +1,225 @@ +package transformers + +import org.jetbrains.dokka.DokkaConfigurationImpl +import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest +import org.junit.jupiter.params.ParameterizedTest +import org.junit.jupiter.params.provider.MethodSource +import testApi.testRunner.dokkaConfiguration +import kotlin.test.assertEquals + +class ObviousAndInheritedFunctionsDocumentableFilterTest : BaseAbstractTest() { + companion object { + @JvmStatic + fun suppressingObviousConfiguration() = listOf(dokkaConfiguration { + suppressInheritedMembers = false + suppressObviousFunctions = true + sourceSets { + sourceSet { + sourceRoots = listOf("src") + } + } + }) + + @JvmStatic + fun nonSuppressingObviousConfiguration() = listOf(dokkaConfiguration { + suppressObviousFunctions = false + suppressInheritedMembers = false + sourceSets { + sourceSet { + sourceRoots = listOf("src") + } + } + }) + + @JvmStatic + fun suppressingInheritedConfiguration() = listOf(dokkaConfiguration { + suppressInheritedMembers = true + suppressObviousFunctions = false + sourceSets { + sourceSet { + sourceRoots = listOf("src") + } + } + }) + + @JvmStatic + fun nonSuppressingInheritedConfiguration() = listOf(dokkaConfiguration { + suppressObviousFunctions = false + suppressInheritedMembers = false + sourceSets { + sourceSet { + sourceRoots = listOf("src") + } + } + }) + } + + + @ParameterizedTest + @MethodSource(value = ["suppressingObviousConfiguration"]) + fun `should suppress toString, equals and hashcode`(suppressingConfiguration: DokkaConfigurationImpl) { + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + data class Suppressed(val x: String) + """.trimIndent(), + suppressingConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + assertEquals(0, functions.size) + } + } + } + + @ParameterizedTest + @MethodSource(value = ["suppressingObviousConfiguration", "suppressingInheritedConfiguration"]) + fun `should suppress toString, equals and hashcode for interface`(suppressingConfiguration: DokkaConfigurationImpl) { + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + interface Suppressed + """.trimIndent(), + suppressingConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + assertEquals(0, functions.size) + } + } + } + + @ParameterizedTest + @MethodSource(value = ["suppressingObviousConfiguration", "suppressingInheritedConfiguration"]) + fun `should suppress toString, equals and hashcode in Java`(suppressingConfiguration: DokkaConfigurationImpl) { + testInline( + """ + /src/suppressed/Suppressed.java + package suppressed; + public class Suppressed { + } + """.trimIndent(), + suppressingConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + assertEquals(0, functions.size) + } + } + } + + @ParameterizedTest + @MethodSource(value = ["suppressingObviousConfiguration"]) + fun `should suppress toString, equals and hashcode but keep custom ones`(suppressingConfiguration: DokkaConfigurationImpl) { + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + data class Suppressed(val x: String) { + override fun toString(): String { + return "custom" + } + } + """.trimIndent(), + suppressingConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + assertEquals(listOf("toString"), functions.map { it.name }) + } + } + } + + @ParameterizedTest + @MethodSource(value = ["suppressingObviousConfiguration", "suppressingInheritedConfiguration"]) + fun `should suppress toString, equals and hashcode but keep custom ones in Java`(suppressingConfiguration: DokkaConfigurationImpl) { + testInline( + """ + /src/suppressed/Suppressed.java + package suppressed; + public class Suppressed { + @Override + public String toString() { + return ""; + } + } + """.trimIndent(), + suppressingConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + assertEquals(listOf("toString"), functions.map { it.name }) + } + } + } + + @ParameterizedTest + @MethodSource(value = ["nonSuppressingObviousConfiguration", "nonSuppressingInheritedConfiguration"]) + fun `should not suppress toString, equals and hashcode if custom config is provided`(nonSuppressingConfiguration: DokkaConfigurationImpl) { + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + data class Suppressed(val x: String) + """.trimIndent(), + nonSuppressingConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + assertEquals( + listOf("copy", "equals", "toString", "component1", "hashCode").sorted(), + functions.map { it.name }.sorted() + ) + } + } + } + + @ParameterizedTest + @MethodSource(value = ["nonSuppressingObviousConfiguration", "nonSuppressingInheritedConfiguration"]) + fun `not should suppress toString, equals and hashcode for interface if custom config is provided`(nonSuppressingConfiguration: DokkaConfigurationImpl) { + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + interface Suppressed + """.trimIndent(), + nonSuppressingConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + assertEquals(listOf("equals", "hashCode", "toString").sorted(), functions.map { it.name }.sorted()) + } + } + } + + @ParameterizedTest + @MethodSource(value = ["nonSuppressingObviousConfiguration", "nonSuppressingInheritedConfiguration"]) + fun `should not suppress toString, equals and hashcode if custom config is provided in Java`(nonSuppressingConfiguration: DokkaConfigurationImpl) { + testInline( + """ + /src/suppressed/Suppressed.java + package suppressed; + public class Suppressed { + } + """.trimIndent(), + nonSuppressingConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + //I would normally just assert names but this would make it JDK dependent, so this is better + assertEquals( + 5, + setOf( + "equals", + "hashCode", + "toString", + "notify", + "notifyAll" + ).intersect(functions.map { it.name }).size + ) + } + } + } +} \ No newline at end of file diff --git a/plugins/base/src/test/kotlin/transformers/ObviousFunctionsDocumentableFilterTest.kt b/plugins/base/src/test/kotlin/transformers/ObviousFunctionsDocumentableFilterTest.kt deleted file mode 100644 index d666b8a7..00000000 --- a/plugins/base/src/test/kotlin/transformers/ObviousFunctionsDocumentableFilterTest.kt +++ /dev/null @@ -1,184 +0,0 @@ -package transformers - -import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest -import org.junit.jupiter.api.Test -import kotlin.test.assertEquals - -class ObviousFunctionsDocumentableFilterTest : BaseAbstractTest() { - val suppressingConfiguration = dokkaConfiguration { - sourceSets { - sourceSet { - sourceRoots = listOf("src") - } - } - } - - val nonSuppressingConfiguration = dokkaConfiguration { - suppressObviousFunctions = false - sourceSets { - sourceSet { - sourceRoots = listOf("src") - } - } - } - - @Test - fun `should suppress toString, equals and hashcode`() { - testInline( - """ - /src/suppressed/Suppressed.kt - package suppressed - data class Suppressed(val x: String) - """.trimIndent(), - suppressingConfiguration - ) { - preMergeDocumentablesTransformationStage = { modules -> - val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } - assertEquals(0, functions.size) - } - } - } - - @Test - fun `should suppress toString, equals and hashcode for interface`() { - testInline( - """ - /src/suppressed/Suppressed.kt - package suppressed - interface Suppressed - """.trimIndent(), - suppressingConfiguration - ) { - preMergeDocumentablesTransformationStage = { modules -> - val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } - assertEquals(0, functions.size) - } - } - } - - @Test - fun `should suppress toString, equals and hashcode in Java`() { - testInline( - """ - /src/suppressed/Suppressed.java - package suppressed; - public class Suppressed { - } - """.trimIndent(), - suppressingConfiguration - ) { - preMergeDocumentablesTransformationStage = { modules -> - val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } - assertEquals(0, functions.size) - } - } - } - - @Test - fun `should suppress toString, equals and hashcode but keep custom ones`() { - testInline( - """ - /src/suppressed/Suppressed.kt - package suppressed - data class Suppressed(val x: String) { - override fun toString(): String { - return "custom" - } - } - """.trimIndent(), - suppressingConfiguration - ) { - preMergeDocumentablesTransformationStage = { modules -> - val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } - assertEquals(listOf("toString"), functions.map { it.name }) - } - } - } - - @Test - fun `should suppress toString, equals and hashcode but keep custom ones in Java`() { - testInline( - """ - /src/suppressed/Suppressed.java - package suppressed; - public class Suppressed { - @Override - public String toString() { - return ""; - } - } - """.trimIndent(), - suppressingConfiguration - ) { - preMergeDocumentablesTransformationStage = { modules -> - val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } - assertEquals(listOf("toString"), functions.map { it.name }) - } - } - } - - @Test - fun `should not suppress toString, equals and hashcode if custom config is provided`() { - testInline( - """ - /src/suppressed/Suppressed.kt - package suppressed - data class Suppressed(val x: String) - """.trimIndent(), - nonSuppressingConfiguration - ) { - preMergeDocumentablesTransformationStage = { modules -> - val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } - assertEquals( - listOf("copy", "equals", "toString", "component1", "hashCode").sorted(), - functions.map { it.name }.sorted() - ) - } - } - } - - @Test - fun `not should suppress toString, equals and hashcode for interface if custom config is provided`() { - testInline( - """ - /src/suppressed/Suppressed.kt - package suppressed - interface Suppressed - """.trimIndent(), - nonSuppressingConfiguration - ) { - preMergeDocumentablesTransformationStage = { modules -> - val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } - assertEquals(listOf("equals", "hashCode", "toString").sorted(), functions.map { it.name }.sorted()) - } - } - } - - @Test - fun `should not suppress toString, equals and hashcode if custom config is provided in Java`() { - testInline( - """ - /src/suppressed/Suppressed.java - package suppressed; - public class Suppressed { - } - """.trimIndent(), - nonSuppressingConfiguration - ) { - preMergeDocumentablesTransformationStage = { modules -> - val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } - //I would normally just assert names but this would make it JDK dependent, so this is better - assertEquals( - 5, - setOf( - "equals", - "hashCode", - "toString", - "notify", - "notifyAll" - ).intersect(functions.map { it.name }).size - ) - } - } - } -} \ No newline at end of file -- cgit