Add constructor keyword (#2691)

2 files changed, 173 insertions, 50 deletions

diff --git a/plugins/base/src/test/kotlin/content/functions/ContentForBriefTest.kt b/plugins/base/src/test/kotlin/content/functions/ContentForBriefTest.kt
index 50f9e357..f86506af 100644
--- a/plugins/base/src/test/kotlin/content/functions/ContentForBriefTest.kt
+++ b/plugins/base/src/test/kotlin/content/functions/ContentForBriefTest.kt
@@ -1,12 +1,14 @@
 package content.functions
 
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.links.TypeConstructor
 import org.jetbrains.dokka.model.DClass
 import org.jetbrains.dokka.model.dfs
 import org.jetbrains.dokka.pages.*
-import org.junit.Assert.assertEquals
+import org.junit.jupiter.api.Assertions.assertEquals
 import org.junit.jupiter.api.Test
+import kotlin.test.assertNotNull
 import kotlin.test.assertNull
 
 
@@ -55,26 +57,19 @@ class ContentForBriefTest : BaseAbstractTest() {
             |}
         """.trimIndent()
 
+
     @Test
     fun `primary constructor should not inherit docs from its parameter`() {
         testInline(codeWithSecondaryAndPrimaryConstructorsDocumented, testConfiguration) {
             pagesTransformationStage = { module ->
-                val classPage =
-                    module.dfs { it.name == "Example" && (it as WithDocumentables).documentables.firstOrNull() is DClass } as ContentPage
-                val constructorsTable =
-                    classPage.content.dfs { it is ContentTable && it.dci.kind == ContentKind.Constructors } as ContentTable
+                val classPage = module.findClassPage("Example")
 
-                assertEquals(2, constructorsTable.children.size)
-                val primary = constructorsTable.children.first {
-                    it.dci.dri.first().callable?.params?.first() == TypeConstructor(
-                        "kotlin.Int",
-                        emptyList()
-                    )
+                val constructorsWithBriefs = classPage.findConstructorsWithBriefs()
+                val constructorDocs = constructorsWithBriefs.findConstructorDocs {
+                    it.callable?.params?.first() == TypeConstructor("kotlin.Int", emptyList())
                 }
-                val primaryConstructorDocs =
-                    primary.dfs { it is ContentText && it.dci.kind == ContentKind.Comment } as ContentText
 
-                assertEquals("constructor docs", primaryConstructorDocs.text)
+                assertEquals("constructor docs", constructorDocs.text)
             }
         }
     }
@@ -83,32 +78,47 @@ class ContentForBriefTest : BaseAbstractTest() {
     fun `secondary constructor should not inherit docs from its parameter`() {
         testInline(codeWithSecondaryAndPrimaryConstructorsDocumented, testConfiguration) {
             pagesTransformationStage = { module ->
-                val classPage =
-                    module.dfs { it.name == "Example" && (it as WithDocumentables).documentables.firstOrNull() is DClass } as ContentPage
-                val constructorsTable =
-                    classPage.content.dfs { it is ContentTable && it.dci.kind == ContentKind.Constructors } as ContentTable
+                val classPage = module.findClassPage("Example")
 
-                assertEquals(2, constructorsTable.children.size)
-                val primary = constructorsTable.children.first {
-                    it.dci.dri.first().callable?.params?.first() == TypeConstructor(
-                        "kotlin.String",
-                        emptyList()
-                    )
+                val constructorsWithBriefs = classPage.findConstructorsWithBriefs()
+                val constructorDocs = constructorsWithBriefs.findConstructorDocs {
+                    it.callable?.params?.first() == TypeConstructor("kotlin.String", emptyList())
                 }
-                val primaryConstructorDocs =
-                    primary.dfs { it is ContentText && it.dci.kind == ContentKind.Comment } as ContentText
 
-                assertEquals("secondary constructor", primaryConstructorDocs.text)
+                assertEquals("secondary constructor", constructorDocs.text)
             }
         }
     }
 
+    /**
+     * All constructors are merged in one block (like overloaded functions).
+     * That leads to the structure where content block (`constructorsWithBriefs`) consist of plain list
+     * of constructors and briefs. In that list constructor is above, brief is below.
+     */
+    private fun ContentPage.findConstructorsWithBriefs(): List<ContentNode> {
+        val constructorsTable = this.content.dfs {
+            it is ContentTable && it.dci.kind == ContentKind.Constructors
+        } as ContentTable
+
+        val constructorsWithBriefs = constructorsTable.dfs {
+            it is ContentGroup && it.dci.kind == ContentKind.SourceSetDependentHint
+        }?.children
+        assertNotNull(constructorsWithBriefs, "Content node with constructors and briefs is not found")
+
+        return constructorsWithBriefs
+    }
+
+    private fun List<ContentNode>.findConstructorDocs(constructorMatcher: (DRI) -> Boolean): ContentText {
+        val constructorIndex = this.indexOfFirst { constructorMatcher(it.dci.dri.first()) }
+        return this[constructorIndex + 1] // expect that the relevant comment is below the constructor
+            .dfs { it is ContentText && it.dci.kind == ContentKind.Comment } as ContentText
+    }
+
     @Test
     fun `primary constructor should not inherit docs from its parameter when no specific docs are provided`() {
         testInline(codeWithDocumentedParameter, testConfiguration) {
             pagesTransformationStage = { module ->
-                val classPage =
-                    module.dfs { it.name == "Example" && (it as WithDocumentables).documentables.firstOrNull() is DClass } as ContentPage
+                val classPage = module.findClassPage("Example")
                 val constructorsTable =
                     classPage.content.dfs { it is ContentTable && it.dci.kind == ContentKind.Constructors } as ContentTable
 
@@ -318,8 +328,15 @@ class ContentForBriefTest : BaseAbstractTest() {
         }
     }
 
+    private fun RootPageNode.findClassPage(className: String): ContentPage {
+        return this.dfs {
+            it.name == className && (it as WithDocumentables).documentables.firstOrNull() is DClass
+        } as ContentPage
+    }
+
     private fun RootPageNode.singleFunctionDescription(className: String): ContentGroup {
-        val classPage = dfs { it.name == className && (it as WithDocumentables).documentables.firstOrNull() is DClass } as ContentPage
+        val classPage =
+            dfs { it.name == className && (it as WithDocumentables).documentables.firstOrNull() is DClass } as ContentPage
         val functionsTable =
             classPage.content.dfs { it is ContentTable && it.dci.kind == ContentKind.Functions } as ContentTable
 
diff --git a/plugins/base/src/test/kotlin/content/signatures/ConstructorsSignaturesTest.kt b/plugins/base/src/test/kotlin/content/signatures/ConstructorsSignaturesTest.kt
index 943d1bc4..c8c088f7 100644
--- a/plugins/base/src/test/kotlin/content/signatures/ConstructorsSignaturesTest.kt
+++ b/plugins/base/src/test/kotlin/content/signatures/ConstructorsSignaturesTest.kt
@@ -1,11 +1,9 @@
 package content.signatures
 
 import matchers.content.*
-import org.jetbrains.dokka.pages.ContentPage
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import org.jetbrains.dokka.pages.ContentPage
 import org.junit.jupiter.api.Test
-import utils.ParamAttributes
-import utils.functionSignature
 
 class ConstructorsSignaturesTest : BaseAbstractTest() {
     private val testConfiguration = dokkaConfiguration {
@@ -196,24 +194,133 @@ class ConstructorsSignaturesTest : BaseAbstractTest() {
                         table {
                             group {
                                 link { +"SomeClass" }
-                                functionSignature(
-                                    annotations = emptyMap(),
-                                    visibility = "",
-                                    modifier = "",
-                                    keywords = emptySet(),
-                                    name = "SomeClass"
-                                )
+                                platformHinted {
+                                    group {
+                                        +"constructor"
+                                        +"("
+                                        +")"
+                                    }
+                                    group {
+                                        +"constructor"
+                                        +"("
+                                        group {
+                                            group {
+                                                +"a: "
+                                                group { link { +"String" } }
+                                            }
+                                        }
+                                        +")"
+                                    }
+                                }
+                            }
+                        }
+                        skipAllNotMatching()
+                    }
+                }
+            }
+        }
+    }
+
+
+    @Test
+    fun `class with a few documented constructors`() {
+        testInline(
+            """
+            |/src/main/kotlin/test/source.kt
+            |package test
+            |
+            | /**
+            |  * some comment
+            |  * @constructor ctor comment
+            | **/
+            |class SomeClass(a: String){
+            |    /**
+            |     * ctor one
+            |    **/
+            |    constructor(): this("")
+            |
+            |    /**
+            |     * ctor two
+            |    **/
+            |    constructor(b: Int): this("")
+            |}
+        """.trimIndent(), testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val page = module.children.single { it.name == "test" }
+                    .children.single { it.name == "SomeClass" } as ContentPage
+                page.content.assertNode {
+                    group {
+                        header(1) { +"SomeClass" }
+                        platformHinted {
+                            group {
+                                +"class "
+                                link { +"SomeClass" }
+                                +"("
+                                group {
+                                    group {
+                                        +"a: "
+                                        group { link { +"String" } }
+                                    }
+                                }
+                                +")"
                             }
+                            skipAllNotMatching()
+                        }
+                    }
+                    group {
+                        header { +"Constructors" }
+                        table {
                             group {
                                 link { +"SomeClass" }
-                                functionSignature(
-                                    annotations = emptyMap(),
-                                    visibility = "",
-                                    modifier = "",
-                                    keywords = emptySet(),
-                                    name = "SomeClass",
-                                    params = listOf("a" to ParamAttributes(emptyMap(), emptySet(), "String")).toTypedArray()
-                                )
+                                platformHinted {
+                                    group {
+                                        +"constructor"
+                                        +"("
+                                        +")"
+                                    }
+                                    group {
+                                        group {
+                                            group { +"ctor one" }
+                                        }
+                                    }
+                                    group {
+                                        +"constructor"
+                                        +"("
+                                        group {
+                                            group {
+                                                +"b: "
+                                                group {
+                                                    link { +"Int" }
+                                                }
+                                            }
+                                        }
+                                        +")"
+                                    }
+                                    group {
+                                        group {
+                                            group { +"ctor two" }
+                                        }
+                                    }
+                                    group {
+                                        +"constructor"
+                                        +"("
+                                        group {
+                                            group {
+                                                +"a: "
+                                                group {
+                                                    link { +"String" }
+                                                }
+                                            }
+                                        }
+                                        +")"
+                                    }
+                                    group {
+                                        group {
+                                            group { +"ctor comment" }
+                                        }
+                                    }
+                                }
                             }
                         }
                         skipAllNotMatching()
@@ -266,8 +373,7 @@ class ConstructorsSignaturesTest : BaseAbstractTest() {
                                 link { +"SomeClass" }
                                 platformHinted {
                                     group {
-                                        +"fun "
-                                        link { +"SomeClass" }
+                                        +"constructor"
                                         +"("
                                         group {
                                             group {