Do not render constructor pages and blocks and for annotation classes (…

…#2642)
Kotlin · Aug 26, 2022 · 34a8ae1 · 34a8ae1
1 parent c37c971
commit 34a8ae1
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 2 deletions.
diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
@@ -96,7 +96,12 @@ open class DefaultPageCreator(
             }
         }
 
-        val constructors = documentables.flatMap { if (it is WithConstructors) it.constructors else emptyList() }
+        val constructors =
+            if (documentables.shouldRenderConstructors()) {
+                documentables.flatMap { (it as? WithConstructors)?.constructors ?: emptyList() }
+            } else {
+                emptyList()
+            }
 
         val classlikes = documentables.flatMap { it.classlikes }
         val functions = documentables.flatMap { it.filteredFunctions }
@@ -366,7 +371,7 @@ open class DefaultPageCreator(
             group(styles = setOf(ContentStyle.TabbedContent), sourceSets = mainSourcesetData + extensions.sourceSets) {
                 +contentForComments(documentables)
                 val csWithConstructor = classlikes.filterIsInstance<WithConstructors>()
-                if (csWithConstructor.isNotEmpty()) {
+                if (csWithConstructor.isNotEmpty() && documentables.shouldRenderConstructors()) {
                     val constructorsToDocumented = csWithConstructor.flatMap { it.constructors }
                     multiBlock(
                         "Constructors",
@@ -432,6 +437,11 @@ open class DefaultPageCreator(
             }
         }
 
+    // Annotations might have constructors to substitute reflection invocations
+    // and for internal/compiler purposes, but they are not expected to be documented
+    // and instantiated directly under normal circumstances, so constructors should not be rendered.
+    private fun List<Documentable>.shouldRenderConstructors() = !this.any { it is DAnnotation }
+
     @Suppress("UNCHECKED_CAST")
     private inline fun <reified T : TagWrapper> GroupedTags.withTypeUnnamed(): SourceSetDependent<T> =
         (this[T::class] as List<Pair<DokkaSourceSet, T>>?)?.toMap().orEmpty()

diff --git a/...SkippingParenthesisForConstructorsTest.kt → .../signatures/ConstructorsSignaturesTest.kt b/...SkippingParenthesisForConstructorsTest.kt → .../signatures/ConstructorsSignaturesTest.kt
@@ -293,4 +293,49 @@ class ConstructorsSignaturesTest : BaseAbstractTest() {
             }
         }
     }
+
+    @Test
+    fun `should render primary constructor, but not constructors block for annotation class`() {
+        testInline(
+            """
+            |/src/main/kotlin/test/source.kt
+            |package test
+            |
+            |annotation class MyAnnotation(val param: String) {}
+            """.trimIndent(),
+            testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val page = module.children.single { it.name == "test" }
+                    .children.single { it.name == "MyAnnotation" } as ContentPage
+                page.content.assertNode {
+                    group {
+                        header(1) { +"MyAnnotation" }
+                        platformHinted {
+                            group {
+                                +"annotation class "
+                                link { +"MyAnnotation" }
+                                +"("
+                                group {
+                                    group {
+                                        +"val param: "
+                                        group { link { +"String" } }
+                                    }
+                                }
+                                +")"
+                            }
+                        }
+                    }
+                    group {
+                        group {
+                            header { +"Properties" }
+                            table {
+                                skipAllNotMatching()
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
 }