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

2 files changed, 39 insertions, 0 deletions

diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/StdLibDocumentationIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/StdLibDocumentationIntegrationTest.kt
new file mode 100644
index 00000000..ee6f4ea2
--- /dev/null
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/StdLibDocumentationIntegrationTest.kt
@@ -0,0 +1,38 @@
+package org.jetbrains.dokka.it
+
+import java.net.URL
+import kotlin.test.Test
+
+class StdLibDocumentationIntegrationTest {
+
+    /**
+     * Documentation for Enum's synthetic values() and valueOf() functions is only present in source code,
+     * but not present in the descriptors. However, Dokka needs to generate documentation for these functions,
+     * so it ships with hardcoded kdoc templates.
+     *
+     * This test exists to make sure documentation for these hardcoded synthetic functions does not change,
+     * and fails if it does, indicating that it needs to be updated.
+     */
+    @Test
+    fun shouldAssertEnumDocumentationHasNotChanged() {
+        val sourcesLink = "https://raw.githubusercontent.com/JetBrains/kotlin/master/core/builtins/native/kotlin/Enum.kt"
+        val sources = URL(sourcesLink).readText()
+
+        val expectedValuesDoc =
+            "    /**\n" +
+            "     * Returns an array containing the constants of this enum type, in the order they're declared.\n" +
+            "     * This method may be used to iterate over the constants.\n" +
+            "     * @values\n" +
+            "     */"
+        check(sources.contains(expectedValuesDoc))
+
+        val expectedValueOfDoc =
+            "    /**\n" +
+            "     * 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.)\n" +
+            "     * @throws IllegalArgumentException if this enum type has no constant with the specified name\n" +
+            "     * @valueOf\n" +
+            "     */"
+        check(sources.contains(expectedValueOfDoc))
+    }
+}
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt
index 84178fe8..22da0754 100644
--- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt
@@ -7,6 +7,7 @@ import org.jetbrains.dokka.it.gradle.AbstractGradleIntegrationTest
 import org.jetbrains.dokka.it.gradle.BuildVersions
 import org.junit.runners.Parameterized
 import java.io.File
+import java.net.URL
 import kotlin.test.*
 
 class StdlibGradleIntegrationTest(override val versions: BuildVersions) : AbstractGradleIntegrationTest(),