diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api index 9450476bd7..48a7a14a2a 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,30 @@ 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 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 { 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 abstract interface class org/jetbrains/dokka/base/translators/descriptors/ExternalClasslikesTranslator { + 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 { + 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; 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..e996a86593 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 translateClassDescriptor(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..05982301e0 --- /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 { + private val analysis = context.plugin().querySingle { kotlinAnalysis } + + private 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.translateClassDescriptor(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..ec4d1ee958 --- /dev/null +++ b/plugins/base/src/main/kotlin/translators/descriptors/ExternalClasslikesTranslator.kt @@ -0,0 +1,12 @@ +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 + +/** + * Service translating [ClassDescriptor]s of symbols defined outside of documented project to [DClasslike]s. + */ +interface ExternalClasslikesTranslator { + 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 new file mode 100644 index 0000000000..c1dbfc2809 --- /dev/null +++ b/plugins/base/src/main/kotlin/translators/descriptors/ExternalDocumentablesProvider.kt @@ -0,0 +1,22 @@ +package org.jetbrains.dokka.base.translators.descriptors + +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/ExternalDocumentablesTest.kt b/plugins/base/src/test/kotlin/translators/ExternalDocumentablesTest.kt new file mode 100644 index 0000000000..011ae72974 --- /dev/null +++ b/plugins/base/src/test/kotlin/translators/ExternalDocumentablesTest.kt @@ -0,0 +1,139 @@ +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 ExternalDocumentablesTest : 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) + assertEquals("java.util/ArrayList///PointingToDeclaration/", res?.dri?.toString()) + + 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) + assertEquals("kotlinx.coroutines/Job///PointingToDeclaration/", res?.dri?.toString()) + + 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("kotlin.collections/Map.Entry///PointingToDeclaration/", res?.dri?.toString()) + } + } + } +} \ No newline at end of file