From f6504c3e984d5ba7b7e670dba8880f0d561c6c99 Mon Sep 17 00:00:00 2001 From: Oleg Yukhnevich Date: Wed, 15 Nov 2023 19:30:10 +0200 Subject: [PATCH] Don't suppress obvious members in kotlin.Enum and kotlin.Any --- ...faultDescriptorToDocumentableTranslator.kt | 13 ++-- .../kotlin/symbols/plugin/KotlinAnalysis.kt | 4 +- .../DefaultSymbolToDocumentableTranslator.kt | 13 ++-- ...nheritedFunctionsDocumentableFilterTest.kt | 68 +++++++++++++++++++ 4 files changed, 85 insertions(+), 13 deletions(-) diff --git a/dokka-subprojects/analysis-kotlin-descriptors-compiler/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/descriptors/compiler/translator/DefaultDescriptorToDocumentableTranslator.kt b/dokka-subprojects/analysis-kotlin-descriptors-compiler/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/descriptors/compiler/translator/DefaultDescriptorToDocumentableTranslator.kt index 4d5611891f..2bbd77160c 100644 --- a/dokka-subprojects/analysis-kotlin-descriptors-compiler/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/descriptors/compiler/translator/DefaultDescriptorToDocumentableTranslator.kt +++ b/dokka-subprojects/analysis-kotlin-descriptors-compiler/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/descriptors/compiler/translator/DefaultDescriptorToDocumentableTranslator.kt @@ -612,7 +612,7 @@ private class DokkaDescriptorVisitor( descriptor.additionalExtras().toSourceSetDependent().toAdditionalModifiers(), (descriptor.getAnnotations() + descriptor.fileLevelAnnotations()).toSourceSetDependent() .toAnnotations(), - ObviousMember.takeIf { descriptor.isObvious() }, + ObviousMember.takeIf { descriptor.isObvious(inheritedFrom) }, ) ) } @@ -640,15 +640,16 @@ private class DokkaDescriptorVisitor( .takeIf { parent.dri.classNames != this.classNames || parent.dri.packageName != this.packageName } } - private fun FunctionDescriptor.isObvious(): Boolean { + private fun FunctionDescriptor.isObvious(inheritedFrom: DRI?): Boolean { return kind == CallableMemberDescriptor.Kind.FAKE_OVERRIDE || (kind == CallableMemberDescriptor.Kind.SYNTHESIZED && !syntheticDocProvider.isDocumented(this)) - || containingDeclaration.fqNameOrNull()?.isObvious() == true + || inheritedFrom?.isObvious() == true } - private fun FqName.isObvious(): Boolean = with(this.asString()) { - return this == "kotlin.Any" || this == "kotlin.Enum" - || this == "java.lang.Object" || this == "java.lang.Enum" + private fun DRI.isObvious(): Boolean = when (packageName) { + "kotlin" -> classNames == "Any" || classNames == "Enum" + "java.lang" -> classNames == "Object" || classNames == "Enum" + else -> false } suspend fun visitConstructorDescriptor(descriptor: ConstructorDescriptor, parent: DRIWithPlatformInfo): DFunction { diff --git a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/KotlinAnalysis.kt b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/KotlinAnalysis.kt index e074a14239..866360d749 100644 --- a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/KotlinAnalysis.kt +++ b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/plugin/KotlinAnalysis.kt @@ -54,7 +54,9 @@ internal fun getLanguageVersionSettings( apiVersion = apiVersion, analysisFlags = hashMapOf( // special flag for Dokka // force to resolve light classes (lazily by default) - AnalysisFlags.eagerResolveOfLightClasses to true + AnalysisFlags.eagerResolveOfLightClasses to true, + // TODO: looks like we need to hide it under a flag? + AnalysisFlags.allowKotlinPackage to true ) ) } diff --git a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt index 298d0182ca..5faee41cdb 100644 --- a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt +++ b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt @@ -742,7 +742,7 @@ internal class DokkaSymbolVisitor( functionSymbol.additionalExtras()?.toSourceSetDependent()?.toAdditionalModifiers(), getDokkaAnnotationsFrom(functionSymbol) ?.toSourceSetDependent()?.toAnnotations(), - ObviousMember.takeIf { isObvious(functionSymbol) }, + ObviousMember.takeIf { isObvious(functionSymbol, inheritedFrom) }, ) ) } @@ -865,14 +865,15 @@ internal class DokkaSymbolVisitor( else getKDocDocumentationFrom(symbol, logger) ?: javadocParser?.let { getJavaDocDocumentationFrom(symbol, it) } - private fun KtAnalysisSession.isObvious(functionSymbol: KtFunctionSymbol): Boolean { + private fun KtAnalysisSession.isObvious(functionSymbol: KtFunctionSymbol, inheritedFrom: DRI?): Boolean { return functionSymbol.origin == KtSymbolOrigin.SOURCE_MEMBER_GENERATED && !hasGeneratedKDocDocumentation(functionSymbol) || - !functionSymbol.isOverride && functionSymbol.callableIdIfNonLocal?.classId?.isObvious() == true + !functionSymbol.isOverride && inheritedFrom?.isObvious() == true } - private fun ClassId.isObvious(): Boolean = with(asString()) { - return this == "kotlin/Any" || this == "kotlin/Enum" - || this == "java.lang/Object" || this == "java.lang/Enum" + private fun DRI.isObvious(): Boolean = when (packageName) { + "kotlin" -> classNames == "Any" || classNames == "Enum" + "java.lang" -> classNames == "Object" || classNames == "Enum" + else -> false } private fun KtSymbol.getSource() = KtPsiDocumentableSource(psi).toSourceSetDependent() diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt index d035948f7b..481e98b50a 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/transformers/ObviousAndInheritedFunctionsDocumentableFilterTest.kt @@ -62,6 +62,26 @@ class ObviousAndInheritedFunctionsDocumentableFilterTest : BaseAbstractTest() { @ParameterizedTest @MethodSource(value = ["suppressingObviousConfiguration"]) fun `should suppress toString, equals and hashcode`(suppressingConfiguration: DokkaConfigurationImpl) { + testInline( + """ + /src/suppressed/Suppressed.kt + package suppressed + class Suppressed(val x: String) { + fun custom() {} + } + """.trimIndent(), + suppressingConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + assertEquals(1, functions.size) + } + } + } + + @ParameterizedTest + @MethodSource(value = ["suppressingObviousConfiguration"]) + fun `should suppress toString, equals and hashcode for data class`(suppressingConfiguration: DokkaConfigurationImpl) { testInline( """ /src/suppressed/Suppressed.kt @@ -226,4 +246,52 @@ class ObviousAndInheritedFunctionsDocumentableFilterTest : BaseAbstractTest() { } } } + + @ParameterizedTest + @MethodSource(value = ["suppressingObviousConfiguration"]) + fun `should not suppress toString, equals and hashcode of kotlin Any`(suppressingConfiguration: DokkaConfigurationImpl) { + testInline( + """ + /src/Any.kt + package kotlin + public open class Any { + public open fun equals(other: Any?): Boolean + public open fun hashCode(): Int + public open fun toString(): String + } + """.trimIndent(), + suppressingConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + assertEquals(3, functions.size) + } + } + } + + @ParameterizedTest + @MethodSource(value = ["suppressingObviousConfiguration"]) + fun `should not suppress toString, equals and hashcode of kotlin Enum`(suppressingConfiguration: DokkaConfigurationImpl) { + testInline( + """ + /src/Enum.kt + package kotlin + public abstract class Enum>(name: String, ordinal: Int): Comparable { + public override final fun compareTo(other: E): Int + public override final fun equals(other: Any?): Boolean + public override final fun hashCode(): Int + public override fun toString(): String + } + """.trimIndent(), + suppressingConfiguration + ) { + preMergeDocumentablesTransformationStage = { modules -> + val functions = modules.flatMap { it.packages }.flatMap { it.classlikes }.flatMap { it.functions } + // TODO: fails on K2 (functions.size=5) + // for some reason functions contains getDeclaringClass from Enum.java + // no such function exists when using K1 + assertEquals(4, functions.size) + } + } + } }