aboutsummaryrefslogtreecommitdiff
path: root/plugins/base/src
diff options
context:
space:
mode:
Diffstat (limited to 'plugins/base/src')
-rw-r--r--plugins/base/src/main/kotlin/DokkaBase.kt11
-rw-r--r--plugins/base/src/main/kotlin/transformers/documentables/ObviousFunctionsDocumentableFilterTransformer.kt11
-rw-r--r--plugins/base/src/main/kotlin/transformers/documentables/SuppressTagDocumentableFilter.kt2
-rw-r--r--plugins/base/src/main/kotlin/transformers/documentables/SuppressedByConditionDocumentableFilterTransformer.kt (renamed from plugins/base/src/main/kotlin/transformers/documentables/SuppressedByTagDocumentableFilterTransformer.kt)2
-rw-r--r--plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt4
-rw-r--r--plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt17
-rw-r--r--plugins/base/src/test/kotlin/transformers/ObviousFunctionsDocumentableFilterTest.kt144
-rw-r--r--plugins/base/src/test/kotlin/transformers/SuppressTagFilterTest.kt14
-rw-r--r--plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt1
9 files changed, 188 insertions, 18 deletions
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")
generated by cgit (git 2.46.0) at 2024-11-23 19:14:18 +0000