diff options
16 files changed, 208 insertions, 22 deletions
diff --git a/core/src/main/kotlin/configuration.kt b/core/src/main/kotlin/configuration.kt index a3989ebc..1501ab2f 100644 --- a/core/src/main/kotlin/configuration.kt +++ b/core/src/main/kotlin/configuration.kt @@ -32,6 +32,7 @@ object DokkaDefaults { const val sourceSetName = "main" val moduleVersion: String? = null val pluginsConfiguration = mutableListOf<PluginConfigurationImpl>() + const val suppressObviousFunctions = true } enum class Platform(val key: String) { @@ -98,6 +99,7 @@ interface DokkaConfiguration : Serializable { val pluginsClasspath: List<File> val pluginsConfiguration: List<PluginConfiguration> val delayTemplateSubstitution: Boolean + val suppressObviousFunctions: Boolean enum class SerializationFormat : Serializable { JSON, XML diff --git a/core/src/main/kotlin/defaultConfiguration.kt b/core/src/main/kotlin/defaultConfiguration.kt index 869a99ed..ec1dde8e 100644 --- a/core/src/main/kotlin/defaultConfiguration.kt +++ b/core/src/main/kotlin/defaultConfiguration.kt @@ -16,6 +16,7 @@ data class DokkaConfigurationImpl( override val modules: List<DokkaModuleDescriptionImpl> = emptyList(), override val failOnWarning: Boolean = DokkaDefaults.failOnWarning, override val delayTemplateSubstitution: Boolean = false, + override val suppressObviousFunctions: Boolean = DokkaDefaults.suppressObviousFunctions, ) : DokkaConfiguration data class PluginConfigurationImpl( diff --git a/core/src/main/kotlin/model/documentableProperties.kt b/core/src/main/kotlin/model/documentableProperties.kt index 209a6296..90ab3053 100644 --- a/core/src/main/kotlin/model/documentableProperties.kt +++ b/core/src/main/kotlin/model/documentableProperties.kt @@ -33,4 +33,8 @@ data class ExceptionInSupertypes(val exceptions: SourceSetDependent<List<TypeCon } override val key: ExtraProperty.Key<Documentable, *> = ExceptionInSupertypes +} + +object ObviousMember : ExtraProperty<Documentable>, ExtraProperty.Key<Documentable, ObviousMember> { + override val key: ExtraProperty.Key<Documentable, *> = this }
\ No newline at end of file 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 87e85c02..82f6da3a 100644 --- a/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt +++ b/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt @@ -34,6 +34,7 @@ class TestDokkaConfigurationBuilder { var pluginsConfigurations: MutableList<PluginConfigurationImpl> = mutableListOf() var failOnWarning: Boolean = false var modules: List<DokkaModuleDescriptionImpl> = emptyList() + var suppressObviousFunctions: Boolean = DokkaDefaults.suppressObviousFunctions private val lazySourceSets = mutableListOf<Lazy<DokkaSourceSetImpl>>() fun build() = DokkaConfigurationImpl( @@ -47,6 +48,7 @@ class TestDokkaConfigurationBuilder { pluginsConfiguration = pluginsConfigurations, modules = modules, failOnWarning = failOnWarning, + suppressObviousFunctions = suppressObviousFunctions ) fun sourceSets(block: SourceSetsBuilder.() -> Unit) { diff --git a/plugins/android-documentation/src/main/kotlin/transformers/HideTagDocumentableFilter.kt b/plugins/android-documentation/src/main/kotlin/transformers/HideTagDocumentableFilter.kt index 074413cc..a8db6668 100644 --- a/plugins/android-documentation/src/main/kotlin/transformers/HideTagDocumentableFilter.kt +++ b/plugins/android-documentation/src/main/kotlin/transformers/HideTagDocumentableFilter.kt @@ -1,13 +1,13 @@ package org.jetbrains.dokka.android.transformers -import org.jetbrains.dokka.base.transformers.documentables.SuppressedByTagDocumentableFilterTransformer +import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer import org.jetbrains.dokka.model.Documentable import org.jetbrains.dokka.model.dfs import org.jetbrains.dokka.model.doc.CustomTagWrapper import org.jetbrains.dokka.plugability.DokkaContext class HideTagDocumentableFilter(val dokkaContext: DokkaContext) : - SuppressedByTagDocumentableFilterTransformer(dokkaContext) { + SuppressedByConditionDocumentableFilterTransformer(dokkaContext) { override fun shouldBeSuppressed(d: Documentable): Boolean = d.documentation.any { (_, docs) -> docs.dfs { it is CustomTagWrapper && it.name.trim() == "hide" } != null } }
\ No newline at end of file diff --git a/plugins/android-documentation/src/test/kotlin/transformers/HideTagDocumentableFilterTest.kt b/plugins/android-documentation/src/test/kotlin/transformers/HideTagDocumentableFilterTest.kt index 01a802bf..82375201 100644 --- a/plugins/android-documentation/src/test/kotlin/transformers/HideTagDocumentableFilterTest.kt +++ b/plugins/android-documentation/src/test/kotlin/transformers/HideTagDocumentableFilterTest.kt @@ -30,7 +30,7 @@ class HideTagDocumentableFilterTest : BaseAbstractTest() { |} """.trimIndent(), configuration ) { - documentablesFirstTransformationStep = { modules -> + preMergeDocumentablesTransformationStage = { modules -> val testingClass = modules.flatMap { it.packages }.flatMap { it.classlikes }.single() as DClass assertEquals(0, testingClass.functions.size) } @@ -60,7 +60,7 @@ class HideTagDocumentableFilterTest : BaseAbstractTest() { |} """.trimIndent(), configuration ) { - documentablesFirstTransformationStep = { modules -> + preMergeDocumentablesTransformationStage = { modules -> val classes = modules.flatMap { it.packages }.flatMap { it.classlikes }.map { it.name } assertEquals(listOf("Visible"), classes) } diff --git a/plugins/base/src/main/kotlin/DokkaBase.kt b/plugins/base/src/main/kotlin/DokkaBase.kt index 2dbad3a7..5a7164d1 100644 --- a/plugins/base/src/main/kotlin/DokkaBase.kt +++ b/plugins/base/src/main/kotlin/DokkaBase.kt @@ -74,17 +74,22 @@ class DokkaBase : DokkaPlugin() { preMergeDocumentableTransformer providing ::SuppressTagDocumentableFilter } - val documentableVisbilityFilter by extending { + val documentableVisibilityFilter by extending { preMergeDocumentableTransformer providing ::DocumentableVisibilityFilterTransformer } + val obviousFunctionsVisbilityFilter by extending { + preMergeDocumentableTransformer providing ::ObviousFunctionsDocumentableFilterTransformer + } + val emptyPackagesFilter by extending { preMergeDocumentableTransformer providing ::EmptyPackagesFilterTransformer order { after( deprecatedDocumentableFilter, suppressedDocumentableFilter, - documentableVisbilityFilter, - suppressedBySuppressTagDocumentableFilter + documentableVisibilityFilter, + suppressedBySuppressTagDocumentableFilter, + obviousFunctionsVisbilityFilter ) } } diff --git a/plugins/base/src/main/kotlin/transformers/documentables/ObviousFunctionsDocumentableFilterTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/ObviousFunctionsDocumentableFilterTransformer.kt new file mode 100644 index 00000000..57d7268e --- /dev/null +++ b/plugins/base/src/main/kotlin/transformers/documentables/ObviousFunctionsDocumentableFilterTransformer.kt @@ -0,0 +1,11 @@ +package org.jetbrains.dokka.base.transformers.documentables + +import org.jetbrains.dokka.model.DFunction +import org.jetbrains.dokka.model.Documentable +import org.jetbrains.dokka.model.ObviousMember +import org.jetbrains.dokka.plugability.DokkaContext + +class ObviousFunctionsDocumentableFilterTransformer(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) { + override fun shouldBeSuppressed(d: Documentable): Boolean = + context.configuration.suppressObviousFunctions && d is DFunction && d.extra[ObviousMember] != null +}
\ No newline at end of file diff --git a/plugins/base/src/main/kotlin/transformers/documentables/SuppressTagDocumentableFilter.kt b/plugins/base/src/main/kotlin/transformers/documentables/SuppressTagDocumentableFilter.kt index 7efb23ab..a297908d 100644 --- a/plugins/base/src/main/kotlin/transformers/documentables/SuppressTagDocumentableFilter.kt +++ b/plugins/base/src/main/kotlin/transformers/documentables/SuppressTagDocumentableFilter.kt @@ -6,7 +6,7 @@ import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.model.doc.Suppress class SuppressTagDocumentableFilter(val dokkaContext: DokkaContext) : - SuppressedByTagDocumentableFilterTransformer(dokkaContext) { + SuppressedByConditionDocumentableFilterTransformer(dokkaContext) { override fun shouldBeSuppressed(d: Documentable): Boolean = d.documentation.any { (_, docs) -> docs.dfs { it is Suppress } != null } }
\ No newline at end of file diff --git a/plugins/base/src/main/kotlin/transformers/documentables/SuppressedByTagDocumentableFilterTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/SuppressedByConditionDocumentableFilterTransformer.kt index f40abe70..b0bdd4b7 100644 --- a/plugins/base/src/main/kotlin/transformers/documentables/SuppressedByTagDocumentableFilterTransformer.kt +++ b/plugins/base/src/main/kotlin/transformers/documentables/SuppressedByConditionDocumentableFilterTransformer.kt @@ -4,7 +4,7 @@ import org.jetbrains.dokka.model.* import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer -abstract class SuppressedByTagDocumentableFilterTransformer(val context: DokkaContext) : PreMergeDocumentableTransformer { +abstract class SuppressedByConditionDocumentableFilterTransformer(val context: DokkaContext) : PreMergeDocumentableTransformer { override fun invoke(modules: List<DModule>): List<DModule> = modules.map { module -> val (documentable, wasChanged) = processModule(module) diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt index b08c11b8..bc45337a 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt @@ -493,6 +493,7 @@ private class DokkaDescriptorVisitor( descriptor.additionalExtras().toSourceSetDependent().toAdditionalModifiers(), (descriptor.getAnnotations() + descriptor.fileLevelAnnotations()).toSourceSetDependent() .toAnnotations(), + ObviousMember.takeIf { descriptor.isFake }, ) ) } @@ -1036,6 +1037,9 @@ private class DokkaDescriptorVisitor( ?.toList() ?.parallelMap { it.toAnnotation(scope = Annotations.AnnotationScope.FILE) } .orEmpty() + + private val FunctionDescriptor.isFake: Boolean + get() = kind == CallableMemberDescriptor.Kind.FAKE_OVERRIDE || kind == CallableMemberDescriptor.Kind.SYNTHESIZED } private data class AncestryLevel( diff --git a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt index c09d1156..14d57df0 100644 --- a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt @@ -111,11 +111,12 @@ class DefaultPsiToDocumentableTranslator( private val cachedBounds = hashMapOf<String, Bound>() - private fun PsiModifierListOwner.getVisibility() = modifierList?.children?.toList()?.let { ml -> + private fun PsiModifierListOwner.getVisibility() = modifierList?.let { + val ml = it.children.toList() when { - ml.any { it.text == PsiKeyword.PUBLIC } -> JavaVisibility.Public - ml.any { it.text == PsiKeyword.PROTECTED } -> JavaVisibility.Protected - ml.any { it.text == PsiKeyword.PRIVATE } -> JavaVisibility.Private + ml.any { it.text == PsiKeyword.PUBLIC } || it.hasModifierProperty("public") -> JavaVisibility.Public + ml.any { it.text == PsiKeyword.PROTECTED } || it.hasModifierProperty("protected") -> JavaVisibility.Protected + ml.any { it.text == PsiKeyword.PRIVATE } || it.hasModifierProperty("private") -> JavaVisibility.Private else -> JavaVisibility.Default } } ?: JavaVisibility.Default @@ -126,6 +127,9 @@ class DefaultPsiToDocumentableTranslator( private val PsiClassType.shouldBeIgnored: Boolean get() = isClass("java.lang.Enum") || isClass("java.lang.Object") + private val DRI.isObvious: Boolean + get() = packageName == "java.lang" && (classNames == "Object" || classNames == "Enum") + private fun PsiClassType.isClass(qName: String): Boolean { val shortName = qName.substringAfterLast('.') if (className == shortName) { @@ -184,7 +188,7 @@ class DefaultPsiToDocumentableTranslator( ancestryTree.add(AncestryLevel(level, classes.firstOrNull()?.first, interfaces.map { it.first })) superTypes.forEach { type -> - (type as? PsiClassType)?.takeUnless { type.shouldBeIgnored }?.resolve()?.let { + (type as? PsiClassType)?.resolve()?.let { val definedAt = DRI.from(it) it.methods.forEach { method -> val hash = method.hash @@ -392,7 +396,8 @@ class DefaultPsiToDocumentableTranslator( it.toSourceSetDependent().toAdditionalModifiers(), (psi.annotations.toList() .toListOfAnnotations() + it.toListOfAnnotations()).toSourceSetDependent() - .toAnnotations() + .toAnnotations(), + ObviousMember.takeIf { inheritedFrom != null && inheritedFrom.isObvious } ) } ) diff --git a/plugins/base/src/test/kotlin/transformers/ObviousFunctionsDocumentableFilterTest.kt b/plugins/base/src/test/kotlin/transformers/ObviousFunctionsDocumentableFilterTest.kt new file mode 100644 index 00000000..01641131 --- /dev/null +++ b/plugins/base/src/test/kotlin/transformers/ObviousFunctionsDocumentableFilterTest.kt @@ -0,0 +1,144 @@ +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 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 `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 diff --git a/plugins/base/src/test/kotlin/transformers/SuppressTagFilterTest.kt b/plugins/base/src/test/kotlin/transformers/SuppressTagFilterTest.kt index 268f934d..fb8f520e 100644 --- a/plugins/base/src/test/kotlin/transformers/SuppressTagFilterTest.kt +++ b/plugins/base/src/test/kotlin/transformers/SuppressTagFilterTest.kt @@ -34,7 +34,7 @@ class SuppressTagFilterTest : BaseAbstractTest() { |class Suppressed """.trimIndent(), configuration ) { - documentablesFirstTransformationStep = { modules -> + preMergeDocumentablesTransformationStage = { modules -> assertEquals( "NotSuppressed", modules.flatMap { it.packages }.flatMap { it.classlikes }.singleOrNull()?.name @@ -57,7 +57,7 @@ class SuppressTagFilterTest : BaseAbstractTest() { |} """.trimIndent(), configuration ) { - documentablesFirstTransformationStep = { modules -> + preMergeDocumentablesTransformationStage = { modules -> assertNull(modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } .firstOrNull { it.name == "suppressedFun" }) } @@ -81,7 +81,7 @@ class SuppressTagFilterTest : BaseAbstractTest() { |fun notSuppressedFun() { } """.trimIndent(), configuration ) { - documentablesFirstTransformationStep = { modules -> + preMergeDocumentablesTransformationStage = { modules -> assertNull(modules.flatMap { it.packages }.flatMap { it.functions } .firstOrNull { it.name == "suppressedFun" }) } @@ -105,7 +105,7 @@ class SuppressTagFilterTest : BaseAbstractTest() { |typealias notSuppressedTypeAlias = String """.trimIndent(), configuration ) { - documentablesFirstTransformationStep = { modules -> + preMergeDocumentablesTransformationStage = { modules -> assertNull(modules.flatMap { it.packages }.flatMap { it.typealiases } .firstOrNull { it.name == "suppressedTypeAlias" }) assertNotNull(modules.flatMap { it.packages }.flatMap { it.typealiases } @@ -129,7 +129,7 @@ class SuppressTagFilterTest : BaseAbstractTest() { |} """.trimIndent(), configuration ) { - documentablesFirstTransformationStep = { modules -> + preMergeDocumentablesTransformationStage = { modules -> assertNull((modules.flatMap { it.packages }.flatMap { it.classlikes } .firstOrNull { it.name == "Suppressed" } as? WithCompanion)?.companion) } @@ -152,7 +152,7 @@ class SuppressTagFilterTest : BaseAbstractTest() { |} """.trimIndent(), configuration ) { - documentablesFirstTransformationStep = { modules -> + preMergeDocumentablesTransformationStage = { modules -> val testingClass = modules.flatMap { it.packages }.flatMap { it.classlikes }.single() assertNull(testingClass.classlikes.firstOrNull()) } @@ -178,7 +178,7 @@ class SuppressTagFilterTest : BaseAbstractTest() { |} """.trimIndent(), configuration ) { - documentablesFirstTransformationStep = { modules -> + preMergeDocumentablesTransformationStage = { modules -> val testingClass = modules.flatMap { it.packages }.flatMap { it.classlikes }.single() as DEnum assertEquals(listOf("NOT_SUPPRESSED"), testingClass.entries.map { it.name }) } diff --git a/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt b/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt index 85f145ed..50d43e63 100644 --- a/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt +++ b/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt @@ -11,6 +11,7 @@ import org.junit.jupiter.api.Test class DefaultDescriptorToDocumentableTranslatorTest : BaseAbstractTest() { val configuration = dokkaConfiguration { + suppressObviousFunctions = false sourceSets { sourceSet { sourceRoots = listOf("src/main/kotlin") diff --git a/runners/cli/src/main/kotlin/cli/main.kt b/runners/cli/src/main/kotlin/cli/main.kt index 1597ed56..b11ed0dc 100644 --- a/runners/cli/src/main/kotlin/cli/main.kt +++ b/runners/cli/src/main/kotlin/cli/main.kt @@ -69,6 +69,13 @@ class GlobalArguments(args: Array<String>) : DokkaConfiguration { description = "Delay substitution of some elements (usefull for incremental builds of multimodule projects)" ).default(DokkaDefaults.delayTemplateSubstitution) + val noSuppressObviousFunctions: Boolean by parser.option( + ArgType.Boolean, + description = "Document generated or obvious functions like default `toString` or `equals`" + ).default(!DokkaDefaults.suppressObviousFunctions) + + override val suppressObviousFunctions: Boolean by lazy{ !noSuppressObviousFunctions } + val globalPackageOptions by parser.option( ArgType.String, description = "List of package source sets in format \"prefix,-deprecated,-privateApi,+warnUndocumented,+suppress;...\" " |