diff --git a/core/api/core.api b/core/api/core.api index 471f63142a..b7e8e28abf 100644 --- a/core/api/core.api +++ b/core/api/core.api @@ -503,6 +503,7 @@ public final class org/jetbrains/dokka/links/DRIKt { public static final fun getSureClassNames (Lorg/jetbrains/dokka/links/DRI;)Ljava/lang/String; public static final fun nextTarget (Lorg/jetbrains/dokka/links/DriTarget;)Lorg/jetbrains/dokka/links/DriTarget; public static final fun withClass (Lorg/jetbrains/dokka/links/DRI;Ljava/lang/String;)Lorg/jetbrains/dokka/links/DRI; + public static final fun withEnumEntryExtra (Lorg/jetbrains/dokka/links/DRI;)Lorg/jetbrains/dokka/links/DRI; public static final fun withTargetToDeclaration (Lorg/jetbrains/dokka/links/DRI;)Lorg/jetbrains/dokka/links/DRI; } diff --git a/core/src/main/kotlin/links/DRI.kt b/core/src/main/kotlin/links/DRI.kt index c646934ddf..7fb449474d 100644 --- a/core/src/main/kotlin/links/DRI.kt +++ b/core/src/main/kotlin/links/DRI.kt @@ -51,9 +51,19 @@ fun DRI.withClass(name: String) = copy(classNames = if (classNames.isNullOrBlank fun DRI.withTargetToDeclaration() = copy(target = PointingToDeclaration) +fun DRI.withEnumEntryExtra() = copy( + extra = DRIExtraContainer(this.extra).also { it[EnumEntryDRIExtra] = EnumEntryDRIExtra }.encode() +) + val DRI.parent: DRI get() = when { - extra != null -> copy(extra = null) + extra != null -> when { + DRIExtraContainer(extra)[EnumEntryDRIExtra] != null -> copy( + classNames = classNames?.substringBeforeLast(".", "")?.takeIf { it.isNotBlank() }, + extra = null + ) + else -> copy(extra = null) + } target != PointingToDeclaration -> copy(target = PointingToDeclaration) callable != null -> copy(callable = null) classNames != null -> copy(classNames = classNames.substringBeforeLast(".", "").takeIf { it.isNotBlank() }) diff --git a/core/src/main/kotlin/utilities/Html.kt b/core/src/main/kotlin/utilities/Html.kt index 3226ca9daa..874c9fb1f2 100644 --- a/core/src/main/kotlin/utilities/Html.kt +++ b/core/src/main/kotlin/utilities/Html.kt @@ -7,9 +7,9 @@ import java.net.URLEncoder * Replaces symbols reserved in HTML with their respective entities. * Replaces & with &, < with < and > with > */ -fun String.htmlEscape(): String = replace("&", "&").replace("<", "<").replace(">", ">") +fun String.htmlEscape(): String = replace("&", "&").replace("<", "<").replace(">", ">").replace("\"", """) fun String.urlEncoded(): String = URLEncoder.encode(this, "UTF-8") fun String.formatToEndWithHtml() = - if (endsWith(".html") || contains(Regex("\\.html#"))) this else "$this.html" \ No newline at end of file + if (endsWith(".html") || contains(Regex("\\.html#"))) this else "$this.html" diff --git a/kotlin-analysis/src/main/kotlin/org/jetbrains/dokka/analysis/DRIFactory.kt b/kotlin-analysis/src/main/kotlin/org/jetbrains/dokka/analysis/DRIFactory.kt index 5f74c42991..33c9927578 100644 --- a/kotlin-analysis/src/main/kotlin/org/jetbrains/dokka/analysis/DRIFactory.kt +++ b/kotlin-analysis/src/main/kotlin/org/jetbrains/dokka/analysis/DRIFactory.kt @@ -7,6 +7,7 @@ import org.jetbrains.kotlin.descriptors.impl.EnumEntrySyntheticClassDescriptor import org.jetbrains.kotlin.psi.psiUtil.parentsWithSelf import org.jetbrains.kotlin.resolve.descriptorUtil.parentsWithSelf import org.jetbrains.kotlin.utils.addToStdlib.firstIsInstanceOrNull +import org.jetbrains.kotlin.utils.addToStdlib.safeAs fun DRI.Companion.from(descriptor: DeclarationDescriptor) = descriptor.parentsWithSelf.run { val parameter = firstIsInstanceOrNull() @@ -20,7 +21,7 @@ fun DRI.Companion.from(descriptor: DeclarationDescriptor) = descriptor.parentsWi ?.joinToString(separator = ".") { it.name.asString() }, callable = callable?.let { Callable.from(it) }, target = DriTarget.from(parameter ?: descriptor), - extra = if (descriptor is EnumEntrySyntheticClassDescriptor) + extra = if (descriptor is EnumEntrySyntheticClassDescriptor || descriptor.safeAs()?.kind == ClassKind.ENUM_ENTRY) DRIExtraContainer().also { it[EnumEntryDRIExtra] = EnumEntryDRIExtra }.encode() else null ) @@ -31,11 +32,16 @@ fun DRI.Companion.from(psi: PsiElement) = psi.parentsWithSelf.run { val psiField = firstIsInstanceOrNull() val classes = filterIsInstance().filterNot { it is PsiTypeParameter } .toList() // We only want exact PsiClass types, not PsiTypeParameter subtype + val additionalClasses = if (psi is PsiEnumConstant) listOfNotNull(psiField?.name) else emptyList() DRI( packageName = classes.lastOrNull()?.qualifiedName?.substringBeforeLast('.', "") ?: "", - classNames = classes.toList().takeIf { it.isNotEmpty() }?.asReversed()?.mapNotNull { it.name } - ?.joinToString("."), - callable = psiMethod?.let { Callable.from(it) } ?: psiField?.let { Callable.from(it) }, + classNames = (additionalClasses + classes.mapNotNull { it.name }).takeIf { it.isNotEmpty() } + ?.asReversed()?.joinToString("."), + // The fallback strategy test whether psi is not `PsiEnumConstant`. The reason behind this is that + // we need unified DRI for both Java and Kotlin enums, so we can link them properly and treat them alike. + // To achieve that, we append enum name to classNames list and leave the callable part set to null. For Kotlin enums + // it is by default, while for Java enums we have to explicitly test for that in this `takeUnless` condition. + callable = psiMethod?.let { Callable.from(it) } ?: psiField?.takeUnless { psi is PsiEnumConstant }?.let { Callable.from(it) }, target = DriTarget.from(psi), extra = if (psi is PsiEnumConstant) DRIExtraContainer().also { it[EnumEntryDRIExtra] = EnumEntryDRIExtra }.encode() diff --git a/plugins/base/src/main/kotlin/resolvers/external/javadoc/JavadocExternalLocationProvider.kt b/plugins/base/src/main/kotlin/resolvers/external/javadoc/JavadocExternalLocationProvider.kt index 84445d2a05..a1f1542dbb 100644 --- a/plugins/base/src/main/kotlin/resolvers/external/javadoc/JavadocExternalLocationProvider.kt +++ b/plugins/base/src/main/kotlin/resolvers/external/javadoc/JavadocExternalLocationProvider.kt @@ -30,13 +30,10 @@ open class JavadocExternalLocationProvider( return "$docWithModule$packageLink/package-summary$extension".htmlEscape() } - // in Kotlin DRI of enum entry is not callable if (DRIExtraContainer(extra)[EnumEntryDRIExtra] != null) { - val (classSplit, enumEntityAnchor) = if (callable == null) { - val lastIndex = classNames?.lastIndexOf(".") ?: 0 + val lastIndex = classNames?.lastIndexOf(".") ?: 0 + val (classSplit, enumEntityAnchor) = classNames?.substring(0, lastIndex) to classNames?.substring(lastIndex + 1) - } else - classNames to callable?.name val classLink = if (packageLink == null) "${classSplit}$extension" else "$packageLink/${classSplit}$extension" diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt index 04716e1632..d336fac138 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt @@ -306,7 +306,7 @@ private class DokkaDescriptorVisitor( val classlikes = async { descriptorsWithKind.classlikes.visitClasslikes(driWithPlatform) } DEnumEntry( - dri = driWithPlatform.dri, + dri = driWithPlatform.dri.withEnumEntryExtra(), name = descriptor.name.asString(), documentation = descriptor.resolveDescriptorData(), functions = functions.await(), diff --git a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt index e7028ef028..79b4798c69 100644 --- a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt @@ -21,11 +21,11 @@ import org.jetbrains.dokka.base.translators.isDirectlyAnException import org.jetbrains.dokka.base.translators.psi.parsers.JavaDocumentationParser import org.jetbrains.dokka.base.translators.psi.parsers.JavadocParser import org.jetbrains.dokka.base.translators.unquotedValue -import org.jetbrains.dokka.links.DRI -import org.jetbrains.dokka.links.nextTarget -import org.jetbrains.dokka.links.withClass +import org.jetbrains.dokka.links.* import org.jetbrains.dokka.model.* import org.jetbrains.dokka.model.AnnotationTarget +import org.jetbrains.dokka.model.Nullable +import org.jetbrains.dokka.model.TypeConstructor import org.jetbrains.dokka.model.doc.DocumentationNode import org.jetbrains.dokka.model.doc.Param import org.jetbrains.dokka.model.properties.PropertyContainer @@ -269,7 +269,7 @@ class DefaultPsiToDocumentableTranslator( name.orEmpty(), fields.filterIsInstance().map { entry -> DEnumEntry( - dri.withClass(entry.name), + dri.withClass(entry.name).withEnumEntryExtra(), entry.name, javadocParser.parseDocumentation(entry).toSourceSetDependent(), null, diff --git a/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt b/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt index f9f591b2de..fd8a49c89b 100644 --- a/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt +++ b/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt @@ -326,7 +326,7 @@ class JavadocParser( dri.toString() } ?: UNRESOLVED_PSI_ELEMENT - return """${label.ifBlank{ defaultLabel().text }}""" + return """${label.ifBlank{ defaultLabel().text }}""" } private fun convertInlineDocTag( diff --git a/plugins/base/src/test/kotlin/enums/EnumsTest.kt b/plugins/base/src/test/kotlin/enums/EnumsTest.kt index 59a4c6f2e8..bfdfa73b27 100644 --- a/plugins/base/src/test/kotlin/enums/EnumsTest.kt +++ b/plugins/base/src/test/kotlin/enums/EnumsTest.kt @@ -125,7 +125,7 @@ class EnumsTest : BaseAbstractTest() { pagesGenerationStage = { module -> val entryPage = module.dfs { it.name == "E1" } as ClasslikePageNode val signaturePart = (entryPage.content.dfs { - it is ContentGroup && it.dci.toString() == "[enums/Test.E1///PointingToDeclaration/][Symbol]" + it is ContentGroup && it.dci.toString() == "[enums/Test.E1///PointingToDeclaration/{\"org.jetbrains.dokka.links.EnumEntryDRIExtra\":{\"key\":\"org.jetbrains.dokka.links.EnumEntryDRIExtra\"}}][Symbol]" } as ContentGroup) assertEquals("(\"e1\", 1, true)", signaturePart.constructorSignature()) } @@ -202,7 +202,7 @@ class EnumsTest : BaseAbstractTest() { ) { pagesTransformationStage = { m -> val entryNode = m.children.first { it.name == "enums" }.children.first { it.name == "Test" }.children.firstIsInstance() - val signature = (entryNode.content as ContentGroup).dfs { it is ContentGroup && it.dci.toString() == "[enums/Test.E1///PointingToDeclaration/][Cover]" } as ContentGroup + val signature = (entryNode.content as ContentGroup).dfs { it is ContentGroup && it.dci.toString() == "[enums/Test.E1///PointingToDeclaration/{\"org.jetbrains.dokka.links.EnumEntryDRIExtra\":{\"key\":\"org.jetbrains.dokka.links.EnumEntryDRIExtra\"}}][Cover]" } as ContentGroup signature.assertNode { header(1) { +"E1" } diff --git a/plugins/base/src/test/kotlin/linking/EnumValuesLinkingTest.kt b/plugins/base/src/test/kotlin/linking/EnumValuesLinkingTest.kt new file mode 100644 index 0000000000..29e705fdd6 --- /dev/null +++ b/plugins/base/src/test/kotlin/linking/EnumValuesLinkingTest.kt @@ -0,0 +1,117 @@ +package linking + +import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest +import org.jetbrains.dokka.links.DRIExtraContainer +import org.jetbrains.dokka.links.EnumEntryDRIExtra +import org.jetbrains.dokka.model.dfs +import org.jetbrains.dokka.model.doc.DocumentationLink +import org.jetbrains.dokka.pages.ContentDRILink +import org.jetbrains.dokka.pages.ContentPage +import org.jetbrains.kotlin.utils.addToStdlib.safeAs +import org.jsoup.Jsoup +import org.junit.jupiter.api.Assertions.* +import org.junit.jupiter.api.Test +import java.nio.file.Paths +import utils.TestOutputWriterPlugin +import java.lang.AssertionError + +class EnumValuesLinkingTest : BaseAbstractTest() { + + @Test + fun `check if enum values are correctly linked`() { + val writerPlugin = TestOutputWriterPlugin() + val testDataDir = getTestDataDir("linking").toAbsolutePath() + testFromData( + dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf(Paths.get("$testDataDir/jvmMain/kotlin").toString()) + analysisPlatform = "jvm" + name = "jvm" + } + } + }, + pluginOverrides = listOf(writerPlugin) + ) { + documentablesTransformationStage = { + val classlikes = it.packages.single().children + assertEquals(4, classlikes.size) + + val javaLinker = classlikes.single { it.name == "JavaLinker" } + javaLinker.documentation.values.single().children.run { + when (val kotlinLink = this[0].children[1].children[1]) { + is DocumentationLink -> kotlinLink.dri.run { + assertEquals("KotlinEnum.ON_CREATE", this.classNames) + assertEquals(null, this.callable) + assertNotNull(DRIExtraContainer(extra)[EnumEntryDRIExtra]) + } + else -> throw AssertionError("Link node is not DocumentationLink type") + } + + when (val javaLink = this[0].children[2].children[1]) { + is DocumentationLink -> javaLink.dri.run { + assertEquals("JavaEnum.ON_DECEIT", this.classNames) + assertEquals(null, this.callable) + assertNotNull(DRIExtraContainer(extra)[EnumEntryDRIExtra]) + } + else -> throw AssertionError("Link node is not DocumentationLink type") + } + } + + val kotlinLinker = classlikes.single { it.name == "KotlinLinker" } + kotlinLinker.documentation.values.single().children.run { + when (val kotlinLink = this[0].children[0].children[5]) { + is DocumentationLink -> kotlinLink.dri.run { + assertEquals("KotlinEnum.ON_CREATE", this.classNames) + assertEquals(null, this.callable) + assertNotNull(DRIExtraContainer(extra)[EnumEntryDRIExtra]) + } + else -> throw AssertionError("Link node is not DocumentationLink type") + } + + when (val javaLink = this[0].children[0].children[9]) { + is DocumentationLink -> javaLink.dri.run { + assertEquals("JavaEnum.ON_DECEIT", this.classNames) + assertEquals(null, this.callable) + assertNotNull(DRIExtraContainer(extra)[EnumEntryDRIExtra]) + } + else -> throw AssertionError("Link node is not DocumentationLink type") + } + } + + assertEquals( + javaLinker.documentation.values.single().children[0].children[1].children[1].safeAs()?.dri, + kotlinLinker.documentation.values.single().children[0].children[0].children[5].safeAs()?.dri + ) + + assertEquals( + javaLinker.documentation.values.single().children[0].children[2].children[1].safeAs()?.dri, + kotlinLinker.documentation.values.single().children[0].children[0].children[9].safeAs()?.dri + ) + } + + renderingStage = { rootPageNode, _ -> + val classlikes = rootPageNode.children.single().children + assertEquals(4, classlikes.size) + + val javaLinker = classlikes.single { it.name == "JavaLinker" } + (javaLinker as ContentPage).run { + assertNotNull(content.dfs { it is ContentDRILink && it.address.classNames == "KotlinEnum.ON_CREATE" }) + assertNotNull(content.dfs { it is ContentDRILink && it.address.classNames == "JavaEnum.ON_DECEIT" }) + } + + val kotlinLinker = classlikes.single { it.name == "KotlinLinker" } + (kotlinLinker as ContentPage).run { + assertNotNull(content.dfs { it is ContentDRILink && it.address.classNames == "KotlinEnum.ON_CREATE" }) + assertNotNull(content.dfs { it is ContentDRILink && it.address.classNames == "JavaEnum.ON_DECEIT" }) + } + + // single method will throw an exception if there is no single element (0 or 2+) + Jsoup.parse(writerPlugin.writer.contents["root/linking.source/-java-linker/index.html"]).select("a[href=\"../-kotlin-enum/-o-n_-c-r-e-a-t-e/index.html\"]").single() + Jsoup.parse(writerPlugin.writer.contents["root/linking.source/-java-linker/index.html"]).select("a[href=\"../-java-enum/-o-n_-d-e-c-e-i-t/index.html\"]").single() + Jsoup.parse(writerPlugin.writer.contents["root/linking.source/-kotlin-linker/index.html"]).select("a[href=\"../-kotlin-enum/-o-n_-c-r-e-a-t-e/index.html\"]").single() + Jsoup.parse(writerPlugin.writer.contents["root/linking.source/-kotlin-linker/index.html"]).select("a[href=\"../-java-enum/-o-n_-d-e-c-e-i-t/index.html\"]").single() + } + } + } +} diff --git a/plugins/base/src/test/kotlin/locationProvider/JavadocExternalLocationProviderTest.kt b/plugins/base/src/test/kotlin/locationProvider/JavadocExternalLocationProviderTest.kt index cb2b0331e3..95179e227b 100644 --- a/plugins/base/src/test/kotlin/locationProvider/JavadocExternalLocationProviderTest.kt +++ b/plugins/base/src/test/kotlin/locationProvider/JavadocExternalLocationProviderTest.kt @@ -45,8 +45,8 @@ class JavadocExternalLocationProviderTest : BaseAbstractTest() { ) val javaDri = DRI( "java.nio.file", - "StandardOpenOption", - Callable("CREATE", null, emptyList()), + "StandardOpenOption.CREATE", + null, PointingToDeclaration, DRIExtraContainer().also { it[EnumEntryDRIExtra] = EnumEntryDRIExtra }.encode() ) diff --git a/plugins/base/src/test/kotlin/model/JavaTest.kt b/plugins/base/src/test/kotlin/model/JavaTest.kt index 886aa0be46..aa132f6e2d 100644 --- a/plugins/base/src/test/kotlin/model/JavaTest.kt +++ b/plugins/base/src/test/kotlin/model/JavaTest.kt @@ -391,8 +391,8 @@ class JavaTest : AbstractModelTest("/src/main/kotlin/java/Test.java", "java") { "RUNTIME", DRI( "java.lang.annotation", - "RetentionPolicy", - DRICallable("RUNTIME", null, emptyList()), + "RetentionPolicy.RUNTIME", + null, PointingToDeclaration, DRIExtraContainer().also { it[EnumEntryDRIExtra] = EnumEntryDRIExtra }.encode() ) diff --git a/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/JavaEnum.java b/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/JavaEnum.java new file mode 100644 index 0000000000..016365a723 --- /dev/null +++ b/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/JavaEnum.java @@ -0,0 +1,5 @@ +package linking.source; + +public enum JavaEnum { + ON_DECEIT, ON_DESTROY; +} diff --git a/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/JavaLinker.java b/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/JavaLinker.java new file mode 100644 index 0000000000..ac416530be --- /dev/null +++ b/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/JavaLinker.java @@ -0,0 +1,8 @@ +package linking.source; + +/** + * Reference link {@link linking.source.KotlinEnum} should resolve

+ * sjuff sjuff {@link linking.source.KotlinEnum#ON_CREATE} should resolve

+ * sjujj sjujj {@link linking.source.JavaEnum#ON_DECEIT} should resolve + */ +public class JavaLinker {} diff --git a/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/KotlinEnum.kt b/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/KotlinEnum.kt new file mode 100644 index 0000000000..a03316b125 --- /dev/null +++ b/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/KotlinEnum.kt @@ -0,0 +1,5 @@ +package linking.source + +enum class KotlinEnum { + ON_CREATE, ON_CATASTROPHE +} diff --git a/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/KotlinLinker.kt b/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/KotlinLinker.kt new file mode 100644 index 0000000000..45afc3d5b1 --- /dev/null +++ b/plugins/base/src/test/resources/linking/jvmMain/kotlin/linking/source/KotlinLinker.kt @@ -0,0 +1,8 @@ +package linking.source + +/** + * Reference link [KotlinEnum] should resolve

+ * stuff stuff [KotlinEnum.ON_CREATE] should resolve

+ * stuff stuff [JavaEnum.ON_DECEIT] should resolve + */ +class KotlinLinker {} diff --git a/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocClasslikeTemplateMapTest.kt b/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocClasslikeTemplateMapTest.kt index 19ef6ae7c0..10240a3f3b 100644 --- a/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocClasslikeTemplateMapTest.kt +++ b/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocClasslikeTemplateMapTest.kt @@ -149,13 +149,13 @@ internal class JavadocClasslikeTemplateMapTest : AbstractJavadocTemplateMapTest( val map = allPagesOfType().first { it.name == "TestClass" }.templateMap assertEquals("TestClass", map["name"]) val signature = assertIsInstance>(map["signature"]) - assertEquals("@Author(name = \"Benjamin Franklin\")", signature["annotations"]) + assertEquals("@Author(name = "Benjamin Franklin")", signature["annotations"]) val methods = assertIsInstance>(map["methods"]) val ownMethods = assertIsInstance>(methods["own"]) val method = assertIsInstance>(ownMethods.single()) val methodSignature = assertIsInstance>(method["signature"]) - assertEquals("@Author(name = \"Franklin D. Roosevelt\")", methodSignature["annotations"]) + assertEquals("@Author(name = "Franklin D. Roosevelt")", methodSignature["annotations"]) } }