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] 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()) } } }