Add documentation for synthetic Enum `values()` and `valueOf()` functions (#2650)

2 files changed, 285 insertions, 1 deletions

diff --git a/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt b/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt
index fe1a42c8..c7e2bc21 100644
--- a/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt
+++ b/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt
@@ -3,6 +3,7 @@ package translators
 import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.links.PointingToDeclaration
 import org.jetbrains.dokka.model.*
 import org.jetbrains.dokka.model.doc.*
 import org.junit.jupiter.api.Assertions.assertEquals
@@ -19,6 +20,7 @@ class DefaultDescriptorToDocumentableTranslatorTest : BaseAbstractTest() {
         sourceSets {
             sourceSet {
                 sourceRoots = listOf("src/main/kotlin")
+                classpath = listOf(commonStdlibPath!!, jvmStdlibPath!!)
             }
         }
     }
@@ -852,6 +854,138 @@ val soapXml = node("soap-env:Envelope", soapAttrs,
             }
         }
     }
+
+    @Test
+    fun `should have documentation for synthetic Enum values functions`() {
+        testInline(
+            """
+            |/src/main/kotlin/test/KotlinEnum.kt
+            |package test
+            |
+            |enum class KotlinEnum {
+            |    FOO, BAR;
+            |}
+            """.trimIndent(),
+            configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val kotlinEnum = module.packages.find { it.name == "test" }
+                    ?.classlikes
+                    ?.single { it.name == "KotlinEnum" }
+                checkNotNull(kotlinEnum)
+                val valuesFunction = kotlinEnum.functions.single { it.name == "values" }
+
+                val expectedValuesType = GenericTypeConstructor(
+                    dri = DRI(
+                        packageName = "kotlin",
+                        classNames = "Array"
+                    ),
+                    projections = listOf(
+                        Invariance(
+                            GenericTypeConstructor(
+                                dri = DRI(
+                                    packageName = "test",
+                                    classNames = "KotlinEnum"
+                                ),
+                                projections = emptyList()
+                            )
+                        )
+                    )
+                )
+                assertEquals(expectedValuesType, valuesFunction.type)
+
+                val expectedDocumentation = DocumentationNode(listOf(
+                    Description(
+                        CustomDocTag(
+                            children = listOf(
+                                P(listOf(
+                                    Text(
+                                        "Returns an array containing the constants of this enum type, in the order " +
+                                                "they're declared."
+                                    ),
+                                )),
+                                P(listOf(
+                                    Text("This method may be used to iterate over the constants.")
+                                ))
+                            ),
+                            name = "MARKDOWN_FILE"
+                        )
+                    )
+                ))
+                assertEquals(expectedDocumentation, valuesFunction.documentation.values.single())
+            }
+        }
+    }
+
+    @Test
+    fun `should have documentation for synthetic Enum valueOf functions`() {
+        testInline(
+            """
+            |/src/main/kotlin/test/KotlinEnum.kt
+            |package test
+            |
+            |enum class KotlinEnum {
+            |    FOO, BAR;
+            |}
+            """.trimIndent(),
+            configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val kotlinEnum = module.packages.find { it.name == "test" }
+                    ?.classlikes
+                    ?.single { it.name == "KotlinEnum" }
+                checkNotNull(kotlinEnum)
+
+                val expectedValueOfType = GenericTypeConstructor(
+                    dri = DRI(
+                        packageName = "test",
+                        classNames = "KotlinEnum"
+                    ),
+                    projections = emptyList()
+                )
+
+                val expectedDocumentation = DocumentationNode(listOf(
+                    Description(
+                        CustomDocTag(
+                            children = listOf(
+                                P(listOf(
+                                    Text(
+                                        "Returns the enum constant of this type with the specified name. " +
+                                            "The string must match exactly an identifier used to declare an enum " +
+                                            "constant in this type. (Extraneous whitespace characters are not permitted.)"
+                                    )
+                                ))
+                            ),
+                            name = "MARKDOWN_FILE"
+                        )
+                    ),
+                    Throws(
+                        root = CustomDocTag(
+                            children = listOf(
+                                P(listOf(
+                                    Text("if this enum type has no constant with the specified name")
+                                ))
+                            ),
+                            name = "MARKDOWN_FILE"
+                        ),
+                        name = "kotlin.IllegalArgumentException",
+                        exceptionAddress = DRI(
+                            packageName = "kotlin",
+                            classNames = "IllegalArgumentException",
+                            target = PointingToDeclaration
+                        ),
+                    )
+                ))
+
+                val valueOfFunction = kotlinEnum.functions.single { it.name == "valueOf" }
+                assertEquals(expectedDocumentation, valueOfFunction.documentation.values.single())
+                assertEquals(expectedValueOfType, valueOfFunction.type)
+
+                val valueOfParamDRI = (valueOfFunction.parameters.single().type as GenericTypeConstructor).dri
+                assertEquals(DRI(packageName = "kotlin", classNames = "String"), valueOfParamDRI)
+            }
+        }
+    }
 }
 
 private sealed class TestSuite {
diff --git a/plugins/base/src/test/kotlin/translators/DefaultPsiToDocumentableTranslatorTest.kt b/plugins/base/src/test/kotlin/translators/DefaultPsiToDocumentableTranslatorTest.kt
index 5f42bd9a..711b9c02 100644
--- a/plugins/base/src/test/kotlin/translators/DefaultPsiToDocumentableTranslatorTest.kt
+++ b/plugins/base/src/test/kotlin/translators/DefaultPsiToDocumentableTranslatorTest.kt
@@ -6,7 +6,7 @@ import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.links.PointingToDeclaration
 import org.jetbrains.dokka.model.*
-import org.jetbrains.dokka.model.doc.Text
+import org.jetbrains.dokka.model.doc.*
 import org.jetbrains.dokka.plugability.DokkaPlugin
 import org.junit.jupiter.api.Assertions
 import org.junit.jupiter.api.Assertions.*
@@ -591,4 +591,154 @@ class DefaultPsiToDocumentableTranslatorTest : BaseAbstractTest() {
             }
         }
     }
+
+    @Test
+    fun `should have documentation for synthetic Enum values functions`() {
+        testInline(
+            """
+            |/src/main/java/test/JavaEnum.java
+            |package test
+            |
+            |public enum JavaEnum {
+            |    FOO, BAR;
+            |}
+            """.trimIndent(),
+            configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val kotlinEnum = module.packages.find { it.name == "test" }
+                    ?.classlikes
+                    ?.single { it.name == "JavaEnum" }
+                checkNotNull(kotlinEnum)
+
+                val valuesFunction = kotlinEnum.functions.single { it.name == "values" }
+
+                val expectedDocumentation = DocumentationNode(listOf(
+                    Description(
+                        CustomDocTag(
+                            children = listOf(
+                                P(listOf(
+                                    Text(
+                                        "Returns an array containing the constants of this enum type, " +
+                                                "in the order they're declared. This method may be used to " +
+                                                "iterate over the constants."
+                                    ),
+                                ))
+                            ),
+                            name = "MARKDOWN_FILE"
+                        )
+                    ),
+                    Return(
+                        CustomDocTag(
+                            children = listOf(
+                                P(listOf(
+                                    Text("an array containing the constants of this enum type, in the order they're declared")
+                                ))
+                            ),
+                            name = "MARKDOWN_FILE"
+                        )
+                    )
+                ))
+                assertEquals(expectedDocumentation, valuesFunction.documentation.values.single())
+
+                val expectedValuesType = GenericTypeConstructor(
+                    dri = DRI(
+                        packageName = "kotlin",
+                        classNames = "Array"
+                    ),
+                    projections = listOf(
+                        GenericTypeConstructor(
+                            dri = DRI(
+                                packageName = "test",
+                                classNames = "JavaEnum"
+                            ),
+                            projections = emptyList()
+                        )
+                    )
+                )
+                assertEquals(expectedValuesType, valuesFunction.type)
+            }
+        }
+    }
+
+    @Test
+    fun `should have documentation for synthetic Enum valueOf functions`() {
+        testInline(
+            """
+            |/src/main/java/test/JavaEnum.java
+            |package test
+            |
+            |public enum JavaEnum {
+            |    FOO, BAR;
+            |}
+            """.trimIndent(),
+            configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val kotlinEnum = module.packages.find { it.name == "test" }
+                    ?.classlikes
+                    ?.single { it.name == "JavaEnum" }
+                checkNotNull(kotlinEnum)
+
+                val valueOfFunction = kotlinEnum.functions.single { it.name == "valueOf" }
+
+                val expectedDocumentation = DocumentationNode(listOf(
+                    Description(
+                        CustomDocTag(
+                            children = listOf(
+                                P(listOf(
+                                    Text(
+                                        "Returns the enum constant of this type with the " +
+                                                "specified name. The string must match exactly an identifier used " +
+                                                "to declare an enum constant in this type. (Extraneous whitespace " +
+                                                "characters are not permitted.)"
+                                    )
+                                ))
+                            ),
+                            name = "MARKDOWN_FILE"
+                        )
+                    ),
+                    Return(
+                        root = CustomDocTag(
+                            children = listOf(
+                                P(listOf(
+                                    Text("the enum constant with the specified name")
+                                ))
+                            ),
+                            name = "MARKDOWN_FILE"
+                        )
+                    ),
+                    Throws(
+                        name = "java.lang.IllegalArgumentException",
+                        exceptionAddress = DRI(
+                            packageName = "java.lang",
+                            classNames = "IllegalArgumentException",
+                            target = PointingToDeclaration
+                        ),
+                        root = CustomDocTag(
+                            children = listOf(
+                                P(listOf(
+                                    Text("if this enum type has no constant with the specified name")
+                                ))
+                            ),
+                            name = "MARKDOWN_FILE"
+                        )
+                    ),
+                ))
+                assertEquals(expectedDocumentation, valueOfFunction.documentation.values.single())
+
+                val expectedValueOfType = GenericTypeConstructor(
+                    dri = DRI(
+                        packageName = "test",
+                        classNames = "JavaEnum"
+                    ),
+                    projections = emptyList()
+                )
+                assertEquals(expectedValueOfType, valueOfFunction.type)
+
+                val valueOfParamDRI = (valueOfFunction.parameters.single().type as GenericTypeConstructor).dri
+                assertEquals(DRI(packageName = "java.lang", classNames = "String"), valueOfParamDRI)
+            }
+        }
+    }
 }