From 86f9559ebd40a07e996df49464fc9101dd21d3bc Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Mon, 26 Sep 2022 18:47:01 +0200 Subject: Add documentation for synthetic Enum `values()` and `valueOf()` functions (#2650) --- ...efaultDescriptorToDocumentableTranslatorTest.kt | 134 ++++++++++++++++++ .../DefaultPsiToDocumentableTranslatorTest.kt | 152 ++++++++++++++++++++- 2 files changed, 285 insertions(+), 1 deletion(-) (limited to 'plugins/base/src/test/kotlin/translators') 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) + } + } + } } -- cgit