Add comments and fix naming

Kotlin · Jan 17, 2022 · 06c1efe · 06c1efe
1 parent 8483c1b
commit 06c1efe
Show file tree

Hide file tree

Showing 5 changed files with 23 additions and 6 deletions.
diff --git a/...base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt b/...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
@@ -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
@@ -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
 }
diff --git 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?
 }
diff --git a/...tlin/translators/ExternalDocumentables.kt → .../translators/ExternalDocumentablesTest.kt b/...tlin/translators/ExternalDocumentables.kt → .../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<DClass>()?.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<DInterface>()?.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())
             }
         }
     }