From b761f04bd2033561f44076db36318cc524f8455c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Marks?= Date: Thu, 13 Jan 2022 18:59:18 +0100 Subject: [PATCH 1/4] Add external documentable provider --- plugins/base/src/main/kotlin/DokkaBase.kt | 13 ++ ...faultDescriptorToDocumentableTranslator.kt | 17 ++- .../DefaultExternalDocumentablesProvider.kt | 42 ++++++ .../ExternalClasslikesTranslator.kt | 9 ++ .../ExternalDocumentablesProvider.kt | 10 ++ .../translators/ExternalDocumentables.kt | 137 ++++++++++++++++++ 6 files changed, 225 insertions(+), 3 deletions(-) create mode 100644 plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt create mode 100644 plugins/base/src/main/kotlin/translators/descriptors/ExternalClasslikesTranslator.kt create mode 100644 plugins/base/src/main/kotlin/translators/descriptors/ExternalDocumentablesProvider.kt create mode 100644 plugins/base/src/test/kotlin/translators/ExternalDocumentables.kt diff --git a/plugins/base/src/main/kotlin/DokkaBase.kt b/plugins/base/src/main/kotlin/DokkaBase.kt index 03fbf64e28..a26f6dcdad 100644 --- a/plugins/base/src/main/kotlin/DokkaBase.kt +++ b/plugins/base/src/main/kotlin/DokkaBase.kt @@ -29,6 +29,9 @@ import org.jetbrains.dokka.base.translators.documentables.DefaultDocumentableToP import org.jetbrains.dokka.base.translators.psi.DefaultPsiToDocumentableTranslator import org.jetbrains.dokka.base.generation.SingleModuleGeneration import org.jetbrains.dokka.base.renderers.html.command.consumers.ReplaceVersionsConsumer +import org.jetbrains.dokka.base.translators.descriptors.DefaultExternalDocumentablesProvider +import org.jetbrains.dokka.base.translators.descriptors.ExternalClasslikesTranslator +import org.jetbrains.dokka.base.translators.descriptors.ExternalDocumentablesProvider import org.jetbrains.dokka.plugability.DokkaPlugin import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer import org.jetbrains.dokka.transformers.pages.PageTransformer @@ -46,6 +49,8 @@ class DokkaBase : DokkaPlugin() { val kotlinAnalysis by extensionPoint() val tabSortingStrategy by extensionPoint() val immediateHtmlCommandConsumer by extensionPoint() + val externalDocumentablesProvider by extensionPoint() + val externalClasslikesTranslator by extensionPoint() val singleGeneration by extending { CoreExtensions.generation providing ::SingleModuleGeneration @@ -252,4 +257,12 @@ class DokkaBase : DokkaPlugin() { val baseSearchbarDataInstaller by extending { htmlPreprocessors providing ::SearchbarDataInstaller order { after(sourceLinksTransformer) } } + + val defaultExternalDocumentablesProvider by extending { + externalDocumentablesProvider providing ::DefaultExternalDocumentablesProvider + } + + val defaultExternalClasslikesTranslator by extending { + externalClasslikesTranslator providing ::DefaultDescriptorToDocumentableTranslator + } } diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt index 04716e1632..c3a6ac338e 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt @@ -2,6 +2,7 @@ package org.jetbrains.dokka.base.translators.descriptors import com.intellij.psi.PsiNamedElement import com.intellij.psi.util.PsiLiteralUtil.* +import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.async import kotlinx.coroutines.coroutineScope import kotlinx.coroutines.runBlocking @@ -55,6 +56,7 @@ import org.jetbrains.kotlin.resolve.constants.KClassValue.Value.LocalClass import org.jetbrains.kotlin.resolve.constants.KClassValue.Value.NormalClass import org.jetbrains.kotlin.resolve.descriptorUtil.annotationClass import org.jetbrains.kotlin.resolve.descriptorUtil.fqNameOrNull +import org.jetbrains.kotlin.resolve.descriptorUtil.parents import org.jetbrains.kotlin.resolve.scopes.MemberScope import org.jetbrains.kotlin.resolve.source.KotlinSourceElement import org.jetbrains.kotlin.resolve.source.PsiSourceElement @@ -79,8 +81,8 @@ import org.jetbrains.kotlin.resolve.constants.BooleanValue as ConstantsBooleanVa import org.jetbrains.kotlin.resolve.constants.NullValue as ConstantsNullValue class DefaultDescriptorToDocumentableTranslator( - context: DokkaContext -) : AsyncSourceToDocumentableTranslator { + private val context: DokkaContext +) : AsyncSourceToDocumentableTranslator, ExternalClasslikesTranslator { private val kotlinAnalysis: KotlinAnalysis = context.plugin().querySingle { kotlinAnalysis } @@ -109,6 +111,15 @@ class DefaultDescriptorToDocumentableTranslator( ) } } + + override fun translateDescriptor(descriptor: ClassDescriptor, sourceSet: DokkaSourceSet): DClasslike { + val driInfo = DRI.from(descriptor.parents.first()).withEmptyInfo() + + return runBlocking(Dispatchers.Default) { + DokkaDescriptorVisitor(sourceSet, kotlinAnalysis[sourceSet].facade, context.logger) + .visitClassDescriptor(descriptor, driInfo) + } + } } data class DRIWithPlatformInfo( @@ -162,7 +173,7 @@ private class DokkaDescriptorVisitor( } } - private suspend fun visitClassDescriptor(descriptor: ClassDescriptor, parent: DRIWithPlatformInfo): DClasslike = + suspend fun visitClassDescriptor(descriptor: ClassDescriptor, parent: DRIWithPlatformInfo): DClasslike = when (descriptor.kind) { ClassKind.ENUM_CLASS -> enumDescriptor(descriptor, parent) ClassKind.OBJECT -> objectDescriptor(descriptor, parent) diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt new file mode 100644 index 0000000000..fa4cd74f06 --- /dev/null +++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt @@ -0,0 +1,42 @@ +package org.jetbrains.dokka.base.translators.descriptors + +import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.DClasslike +import org.jetbrains.dokka.plugability.DokkaContext +import org.jetbrains.dokka.plugability.querySingle +import org.jetbrains.dokka.plugability.plugin +import org.jetbrains.kotlin.descriptors.ClassDescriptor +import org.jetbrains.kotlin.descriptors.DeclarationDescriptor +import org.jetbrains.kotlin.descriptors.PackageViewDescriptor +import org.jetbrains.kotlin.name.FqName +import org.jetbrains.kotlin.resolve.scopes.MemberScope +import org.jetbrains.kotlin.resolve.scopes.getDescriptorsFiltered + +class DefaultExternalDocumentablesProvider(context: DokkaContext) : ExternalDocumentablesProvider { + val analysis = context.plugin().querySingle { kotlinAnalysis } + + val translator = context.plugin().querySingle { externalClasslikesTranslator } + + override fun findClasslike(dri: DRI, sourceSet: DokkaSourceSet): DClasslike? { + val pkg = dri.packageName?.let { FqName(it) } ?: FqName.ROOT + val names = dri.classNames?.split('.') ?: return null + + val packageDsc = analysis[sourceSet].facade.moduleDescriptor.getPackage(pkg) + val classDsc = names.fold(packageDsc) { dsc, name -> + dsc?.scope?.getDescriptorsFiltered { it.identifier == name } + ?.filterIsInstance() + ?.firstOrNull() + } + + return (classDsc as? ClassDescriptor)?.let { translator.translateDescriptor(it, sourceSet) } + } + + private val DeclarationDescriptor.scope: MemberScope + get() = when (this) { + is PackageViewDescriptor -> memberScope + is ClassDescriptor -> unsubstitutedMemberScope + else -> throw IllegalArgumentException("Unexpected type of descriptor: ${this::class}") + } +} \ No newline at end of file diff --git a/plugins/base/src/main/kotlin/translators/descriptors/ExternalClasslikesTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/ExternalClasslikesTranslator.kt new file mode 100644 index 0000000000..bfa9e820cc --- /dev/null +++ b/plugins/base/src/main/kotlin/translators/descriptors/ExternalClasslikesTranslator.kt @@ -0,0 +1,9 @@ +package org.jetbrains.dokka.base.translators.descriptors + +import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet +import org.jetbrains.dokka.model.DClasslike +import org.jetbrains.kotlin.descriptors.ClassDescriptor + +interface ExternalClasslikesTranslator { + fun translateDescriptor(descriptor: ClassDescriptor, sourceSet: DokkaSourceSet): DClasslike +} \ No newline at end of file diff --git a/plugins/base/src/main/kotlin/translators/descriptors/ExternalDocumentablesProvider.kt b/plugins/base/src/main/kotlin/translators/descriptors/ExternalDocumentablesProvider.kt new file mode 100644 index 0000000000..2011b042c0 --- /dev/null +++ b/plugins/base/src/main/kotlin/translators/descriptors/ExternalDocumentablesProvider.kt @@ -0,0 +1,10 @@ +package org.jetbrains.dokka.base.translators.descriptors + +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.DClasslike + + +interface ExternalDocumentablesProvider { + fun findClasslike(dri: DRI, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike? +} \ No newline at end of file diff --git a/plugins/base/src/test/kotlin/translators/ExternalDocumentables.kt b/plugins/base/src/test/kotlin/translators/ExternalDocumentables.kt new file mode 100644 index 0000000000..75144c7ce8 --- /dev/null +++ b/plugins/base/src/test/kotlin/translators/ExternalDocumentables.kt @@ -0,0 +1,137 @@ +package translators + +import com.intellij.openapi.application.PathManager +import kotlinx.coroutines.Job +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest +import org.jetbrains.dokka.base.translators.descriptors.ExternalDocumentablesProvider +import org.jetbrains.dokka.model.DClass +import org.jetbrains.dokka.model.DInterface +import org.jetbrains.dokka.plugability.plugin +import org.jetbrains.dokka.plugability.querySingle +import org.jetbrains.dokka.utilities.cast +import org.junit.jupiter.api.Assertions.assertEquals +import org.junit.jupiter.api.Test + +class ExternalDocumentables : BaseAbstractTest() { + @Test + fun `external documentable from java stdlib`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src") + analysisPlatform = "jvm" + classpath += jvmStdlibPath!! + } + } + } + + testInline( + """ + /src/com/sample/MyList.kt + package com.sample + class MyList: ArrayList() + """.trimIndent(), + configuration + ) { + lateinit var provider: ExternalDocumentablesProvider + pluginsSetupStage = { + provider = it.plugin().querySingle { externalDocumentablesProvider } + } + documentablesTransformationStage = { mod -> + val entry = mod.packages.single().classlikes.single().cast().supertypes.entries.single() + val res = provider.findClasslike( + entry.value.single().typeConstructor.dri, + entry.key) + assertEquals("ArrayList", res?.name) + + val supertypes = res?.cast()?.supertypes?.values?.single() + ?.map { it.typeConstructor.dri.classNames } + assertEquals( + listOf("AbstractList", "RandomAccess", "Cloneable", "Serializable", "MutableList"), + supertypes + ) + } + } + } + + @Test + fun `external documentable from dependency`() { + val coroutinesPath = + PathManager.getResourceRoot(Job::class.java, "/kotlinx/coroutines/Job.class") + + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src") + analysisPlatform = "jvm" + classpath += listOf(jvmStdlibPath!!, coroutinesPath!!) + } + } + } + + testInline( + """ + /src/com/sample/MyJob.kt + package com.sample + import kotlinx.coroutines.Job + abstract class MyJob: Job + """.trimIndent(), + configuration + ) { + lateinit var provider: ExternalDocumentablesProvider + pluginsSetupStage = { + provider = it.plugin().querySingle { externalDocumentablesProvider } + } + documentablesTransformationStage = { mod -> + val entry = mod.packages.single().classlikes.single().cast().supertypes.entries.single() + val res = provider.findClasslike( + entry.value.single().typeConstructor.dri, + entry.key) + assertEquals("Job", res?.name) + + val supertypes = res?.cast()?.supertypes?.values?.single() + ?.map { it.typeConstructor.dri.classNames } + assertEquals( + listOf("CoroutineContext.Element"), + supertypes + ) + } + } + } + + @Test + fun `external documentable for nested class`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src") + analysisPlatform = "jvm" + classpath += jvmStdlibPath!! + } + } + } + + testInline( + """ + /src/com/sample/MyList.kt + package com.sample + abstract class MyEntry: Map.Entry + """.trimIndent(), + configuration + ) { + lateinit var provider: ExternalDocumentablesProvider + pluginsSetupStage = { + provider = it.plugin().querySingle { externalDocumentablesProvider } + } + documentablesTransformationStage = { mod -> + val entry = mod.packages.single().classlikes.single().cast().supertypes.entries.single() + val res = provider.findClasslike( + entry.value.single().typeConstructor.dri, + entry.key) + assertEquals("Entry", res?.name) + assertEquals("Map.Entry", res?.dri?.classNames) + } + } + } +} \ No newline at end of file From b84a80624ca92d70238dc5e7dd702d1cacb94c87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Marks?= Date: Fri, 14 Jan 2022 10:28:24 +0100 Subject: [PATCH 2/4] Update the api spec of base plugin --- plugins/base/api/base.api | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api index 9450476bd7..5f702773af 100644 --- a/plugins/base/api/base.api +++ b/plugins/base/api/base.api @@ -5,6 +5,8 @@ public final class org/jetbrains/dokka/base/DokkaBase : org/jetbrains/dokka/plug public final fun getBaseSearchbarDataInstaller ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getCommentsToContentConverter ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; public final fun getCustomResourceInstaller ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getDefaultExternalClasslikesTranslator ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getDefaultExternalDocumentablesProvider ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDefaultKotlinAnalysis ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDefaultSamplesTransformer ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDefaultTabSortingStrategy ()Lorg/jetbrains/dokka/plugability/Extension; @@ -18,6 +20,8 @@ public final class org/jetbrains/dokka/base/DokkaBase : org/jetbrains/dokka/plug public final fun getEmptyModulesFilter ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getEmptyPackagesFilter ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getExtensionsExtractor ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getExternalClasslikesTranslator ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getExternalDocumentablesProvider ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; public final fun getExternalLocationProviderFactory ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; public final fun getFallbackMerger ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getFileWriter ()Lorg/jetbrains/dokka/plugability/Extension; @@ -1279,16 +1283,32 @@ public final class org/jetbrains/dokka/base/translators/descriptors/DRIWithPlatf public fun toString ()Ljava/lang/String; } -public final class org/jetbrains/dokka/base/translators/descriptors/DefaultDescriptorToDocumentableTranslator : org/jetbrains/dokka/transformers/sources/AsyncSourceToDocumentableTranslator { +public final class org/jetbrains/dokka/base/translators/descriptors/DefaultDescriptorToDocumentableTranslator : org/jetbrains/dokka/base/translators/descriptors/ExternalClasslikesTranslator, org/jetbrains/dokka/transformers/sources/AsyncSourceToDocumentableTranslator { public fun (Lorg/jetbrains/dokka/plugability/DokkaContext;)V public fun invoke (Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/plugability/DokkaContext;)Lorg/jetbrains/dokka/model/DModule; public fun invokeSuspending (Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/plugability/DokkaContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; + public fun translateDescriptor (Lorg/jetbrains/kotlin/descriptors/ClassDescriptor;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/model/DClasslike; } public final class org/jetbrains/dokka/base/translators/descriptors/DefaultDescriptorToDocumentableTranslatorKt { public static final fun withEmptyInfo (Lorg/jetbrains/dokka/links/DRI;)Lorg/jetbrains/dokka/base/translators/descriptors/DRIWithPlatformInfo; } +public final class org/jetbrains/dokka/base/translators/descriptors/DefaultExternalDocumentablesProvider : org/jetbrains/dokka/base/translators/descriptors/ExternalDocumentablesProvider { + public fun (Lorg/jetbrains/dokka/plugability/DokkaContext;)V + public fun findClasslike (Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/model/DClasslike; + public final fun getAnalysis ()Lorg/jetbrains/dokka/analysis/KotlinAnalysis; + public final fun getTranslator ()Lorg/jetbrains/dokka/base/translators/descriptors/ExternalClasslikesTranslator; +} + +public abstract interface class org/jetbrains/dokka/base/translators/descriptors/ExternalClasslikesTranslator { + public abstract fun translateDescriptor (Lorg/jetbrains/kotlin/descriptors/ClassDescriptor;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/model/DClasslike; +} + +public abstract interface class org/jetbrains/dokka/base/translators/descriptors/ExternalDocumentablesProvider { + public abstract fun findClasslike (Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/model/DClasslike; +} + public final class org/jetbrains/dokka/base/translators/documentables/BriefFromContentNodesKt { public static final fun firstParagraphBrief (Lorg/jetbrains/dokka/model/doc/DocTag;)Lorg/jetbrains/dokka/model/doc/DocTag; public static final fun firstSentenceBriefFromContentNodes (Ljava/util/List;)Ljava/util/List; From 8483c1be959d18e85795eac00e716d4678c17f84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Marks?= Date: Fri, 14 Jan 2022 10:32:10 +0100 Subject: [PATCH 3/4] Hide mistakenly exposed fields --- plugins/base/api/base.api | 2 -- .../descriptors/DefaultExternalDocumentablesProvider.kt | 4 ++-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api index 5f702773af..4ab4312f8c 100644 --- a/plugins/base/api/base.api +++ b/plugins/base/api/base.api @@ -1297,8 +1297,6 @@ public final class org/jetbrains/dokka/base/translators/descriptors/DefaultDescr public final class org/jetbrains/dokka/base/translators/descriptors/DefaultExternalDocumentablesProvider : org/jetbrains/dokka/base/translators/descriptors/ExternalDocumentablesProvider { public fun (Lorg/jetbrains/dokka/plugability/DokkaContext;)V public fun findClasslike (Lorg/jetbrains/dokka/links/DRI;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/model/DClasslike; - public final fun getAnalysis ()Lorg/jetbrains/dokka/analysis/KotlinAnalysis; - public final fun getTranslator ()Lorg/jetbrains/dokka/base/translators/descriptors/ExternalClasslikesTranslator; } public abstract interface class org/jetbrains/dokka/base/translators/descriptors/ExternalClasslikesTranslator { diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt index fa4cd74f06..700c3ffc17 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt @@ -15,9 +15,9 @@ import org.jetbrains.kotlin.resolve.scopes.MemberScope import org.jetbrains.kotlin.resolve.scopes.getDescriptorsFiltered class DefaultExternalDocumentablesProvider(context: DokkaContext) : ExternalDocumentablesProvider { - val analysis = context.plugin().querySingle { kotlinAnalysis } + private val analysis = context.plugin().querySingle { kotlinAnalysis } - val translator = context.plugin().querySingle { externalClasslikesTranslator } + private val translator = context.plugin().querySingle { externalClasslikesTranslator } override fun findClasslike(dri: DRI, sourceSet: DokkaSourceSet): DClasslike? { val pkg = dri.packageName?.let { FqName(it) } ?: FqName.ROOT From add4cbf6738d6f5d9a1d0a07bd018348a7e23f5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Marks?= Date: Mon, 17 Jan 2022 11:45:54 +0100 Subject: [PATCH 4/4] Add comments and fix naming --- plugins/base/api/base.api | 4 ++-- .../DefaultDescriptorToDocumentableTranslator.kt | 2 +- .../DefaultExternalDocumentablesProvider.kt | 2 +- .../descriptors/ExternalClasslikesTranslator.kt | 5 ++++- .../descriptors/ExternalDocumentablesProvider.kt | 14 +++++++++++++- ...cumentables.kt => ExternalDocumentablesTest.kt} | 6 ++++-- 6 files changed, 25 insertions(+), 8 deletions(-) rename plugins/base/src/test/kotlin/translators/{ExternalDocumentables.kt => ExternalDocumentablesTest.kt} (93%) diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api index 4ab4312f8c..48a7a14a2a 100644 --- a/plugins/base/api/base.api +++ b/plugins/base/api/base.api @@ -1287,7 +1287,7 @@ public final class org/jetbrains/dokka/base/translators/descriptors/DefaultDescr public fun (Lorg/jetbrains/dokka/plugability/DokkaContext;)V public fun invoke (Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/plugability/DokkaContext;)Lorg/jetbrains/dokka/model/DModule; public fun invokeSuspending (Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/plugability/DokkaContext;Lkotlin/coroutines/Continuation;)Ljava/lang/Object; - public fun translateDescriptor (Lorg/jetbrains/kotlin/descriptors/ClassDescriptor;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/model/DClasslike; + public fun translateClassDescriptor (Lorg/jetbrains/kotlin/descriptors/ClassDescriptor;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/model/DClasslike; } public final class org/jetbrains/dokka/base/translators/descriptors/DefaultDescriptorToDocumentableTranslatorKt { @@ -1300,7 +1300,7 @@ public final class org/jetbrains/dokka/base/translators/descriptors/DefaultExter } public abstract interface class org/jetbrains/dokka/base/translators/descriptors/ExternalClasslikesTranslator { - public abstract fun translateDescriptor (Lorg/jetbrains/kotlin/descriptors/ClassDescriptor;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/model/DClasslike; + public abstract fun translateClassDescriptor (Lorg/jetbrains/kotlin/descriptors/ClassDescriptor;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/model/DClasslike; } public abstract interface class org/jetbrains/dokka/base/translators/descriptors/ExternalDocumentablesProvider { diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt index c3a6ac338e..e996a86593 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt @@ -112,7 +112,7 @@ class DefaultDescriptorToDocumentableTranslator( } } - override fun translateDescriptor(descriptor: ClassDescriptor, sourceSet: DokkaSourceSet): DClasslike { + override fun translateClassDescriptor(descriptor: ClassDescriptor, sourceSet: DokkaSourceSet): DClasslike { val driInfo = DRI.from(descriptor.parents.first()).withEmptyInfo() return runBlocking(Dispatchers.Default) { diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt index 700c3ffc17..05982301e0 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultExternalDocumentablesProvider.kt @@ -30,7 +30,7 @@ class DefaultExternalDocumentablesProvider(context: DokkaContext) : ExternalDocu ?.firstOrNull() } - return (classDsc as? ClassDescriptor)?.let { translator.translateDescriptor(it, sourceSet) } + return (classDsc as? ClassDescriptor)?.let { translator.translateClassDescriptor(it, sourceSet) } } private val DeclarationDescriptor.scope: MemberScope diff --git a/plugins/base/src/main/kotlin/translators/descriptors/ExternalClasslikesTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/ExternalClasslikesTranslator.kt index bfa9e820cc..ec4d1ee958 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/ExternalClasslikesTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/ExternalClasslikesTranslator.kt @@ -4,6 +4,9 @@ import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet import org.jetbrains.dokka.model.DClasslike import org.jetbrains.kotlin.descriptors.ClassDescriptor +/** + * Service translating [ClassDescriptor]s of symbols defined outside of documented project to [DClasslike]s. + */ interface ExternalClasslikesTranslator { - fun translateDescriptor(descriptor: ClassDescriptor, sourceSet: DokkaSourceSet): DClasslike + fun translateClassDescriptor(descriptor: ClassDescriptor, sourceSet: DokkaSourceSet): DClasslike } \ No newline at end of file diff --git a/plugins/base/src/main/kotlin/translators/descriptors/ExternalDocumentablesProvider.kt b/plugins/base/src/main/kotlin/translators/descriptors/ExternalDocumentablesProvider.kt index 2011b042c0..c1dbfc2809 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/ExternalDocumentablesProvider.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/ExternalDocumentablesProvider.kt @@ -4,7 +4,19 @@ import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.links.DRI import org.jetbrains.dokka.model.DClasslike - +/** + * Service that can be queried with [DRI] and source set to obtain a documentable for classlike. + * + * There are some cases when there is a need to process documentables of classlikes that were not defined + * in the project itself but are somehow related to the symbols defined in the documented project (e.g. are supertypes + * of classes defined in project). + */ interface ExternalDocumentablesProvider { + + /** + * Returns [DClasslike] matching provided [DRI] in specified source set. + * + * Result is null if compiler haven't generated matching class descriptor. + */ fun findClasslike(dri: DRI, sourceSet: DokkaConfiguration.DokkaSourceSet): DClasslike? } \ No newline at end of file diff --git a/plugins/base/src/test/kotlin/translators/ExternalDocumentables.kt b/plugins/base/src/test/kotlin/translators/ExternalDocumentablesTest.kt similarity index 93% rename from plugins/base/src/test/kotlin/translators/ExternalDocumentables.kt rename to plugins/base/src/test/kotlin/translators/ExternalDocumentablesTest.kt index 75144c7ce8..011ae72974 100644 --- a/plugins/base/src/test/kotlin/translators/ExternalDocumentables.kt +++ b/plugins/base/src/test/kotlin/translators/ExternalDocumentablesTest.kt @@ -13,7 +13,7 @@ import org.jetbrains.dokka.utilities.cast import org.junit.jupiter.api.Assertions.assertEquals import org.junit.jupiter.api.Test -class ExternalDocumentables : BaseAbstractTest() { +class ExternalDocumentablesTest : BaseAbstractTest() { @Test fun `external documentable from java stdlib`() { val configuration = dokkaConfiguration { @@ -44,6 +44,7 @@ class ExternalDocumentables : BaseAbstractTest() { entry.value.single().typeConstructor.dri, entry.key) assertEquals("ArrayList", res?.name) + assertEquals("java.util/ArrayList///PointingToDeclaration/", res?.dri?.toString()) val supertypes = res?.cast()?.supertypes?.values?.single() ?.map { it.typeConstructor.dri.classNames } @@ -89,6 +90,7 @@ class ExternalDocumentables : BaseAbstractTest() { entry.value.single().typeConstructor.dri, entry.key) assertEquals("Job", res?.name) + assertEquals("kotlinx.coroutines/Job///PointingToDeclaration/", res?.dri?.toString()) val supertypes = res?.cast()?.supertypes?.values?.single() ?.map { it.typeConstructor.dri.classNames } @@ -130,7 +132,7 @@ class ExternalDocumentables : BaseAbstractTest() { entry.value.single().typeConstructor.dri, entry.key) assertEquals("Entry", res?.name) - assertEquals("Map.Entry", res?.dri?.classNames) + assertEquals("kotlin.collections/Map.Entry///PointingToDeclaration/", res?.dri?.toString()) } } }