From 86446ac53fc691a5f894e66e0608b67bbf1c3b60 Mon Sep 17 00:00:00 2001
From: Paweł Marks <pmarks@virtuslab.com>
Date: Mon, 4 Nov 2019 13:58:11 +0100
Subject: Adds information about tags to documentation graphs

---
 core/src/main/kotlin/DokkaDescriptorVisitor.kt  | 26 +++++++++++++---------
 core/src/main/kotlin/Model/DocumentationNode.kt | 29 ++++++++++++++++++++-----
 core/src/main/kotlin/Utilities/nodeDebug.kt     | 19 +++++++---------
 3 files changed, 48 insertions(+), 26 deletions(-)

(limited to 'core/src')

diff --git a/core/src/main/kotlin/DokkaDescriptorVisitor.kt b/core/src/main/kotlin/DokkaDescriptorVisitor.kt
index e2485a2c..979acdc5 100644
--- a/core/src/main/kotlin/DokkaDescriptorVisitor.kt
+++ b/core/src/main/kotlin/DokkaDescriptorVisitor.kt
@@ -9,6 +9,7 @@ import org.jetbrains.kotlin.descriptors.*
 import org.jetbrains.kotlin.descriptors.impl.DeclarationDescriptorVisitorEmptyBodies
 import org.jetbrains.kotlin.resolve.scopes.DescriptorKindFilter
 import org.jetbrains.kotlin.resolve.scopes.MemberScope
+import org.jetbrains.kotlin.idea.kdoc.findKDoc
 
 object DokkaDescriptorVisitor : DeclarationDescriptorVisitorEmptyBodies<DocumentationNode<*>, DRI>() {
     override fun visitDeclarationDescriptor(descriptor: DeclarationDescriptor, parent: DRI): Nothing {
@@ -20,43 +21,48 @@ object DokkaDescriptorVisitor : DeclarationDescriptorVisitorEmptyBodies<Document
         parent: DRI
     ): Package {
         val dri = DRI(packageName = descriptor.fqName.asString())
+        val scope = descriptor.getMemberScope()
         return Package(
             dri,
-            descriptor.getMemberScope().functions(dri),
-            descriptor.getMemberScope().properties(dri),
-            descriptor.getMemberScope().classes(dri)
+            scope.functions(dri),
+            scope.properties(dri),
+            scope.classes(dri)
         )
     }
 
     override fun visitClassDescriptor(descriptor: ClassDescriptor, parent: DRI): Class {
         val dri = parent.withClass(descriptor.name.asString())
+        val scope = descriptor.getMemberScope(emptyList())
         return Class(
             dri,
             descriptor.name.asString(),
-            descriptor.getMemberScope(emptyList()).functions(dri),
-            descriptor.getMemberScope(emptyList()).properties(dri),
-            descriptor.getMemberScope(emptyList()).classes(dri),
+            scope.functions(dri),
+            scope.properties(dri),
+            scope.classes(dri),
+            descriptor.findKDoc(),
             descriptor
         )
     }
 
     override fun visitPropertyDescriptor(descriptor: PropertyDescriptor, parent: DRI): Property {
-        val dri = parent.copy(callable = Callable.Companion.from(descriptor))
+        val dri = parent.copy(callable = Callable.from(descriptor))
         return Property(
             dri,
             descriptor.name.asString(),
             descriptor.extensionReceiverParameter?.let { visitReceiverParameterDescriptor(it, dri) },
+            descriptor.findKDoc(),
             descriptor
         )
     }
 
     override fun visitFunctionDescriptor(descriptor: FunctionDescriptor, parent: DRI): Function {
-        val dri = parent.copy(callable = Callable.Companion.from(descriptor))
+        val dri = parent.copy(callable = Callable.from(descriptor))
         return Function(
             dri,
             descriptor.name.asString(),
             descriptor.extensionReceiverParameter?.let { visitReceiverParameterDescriptor(it, dri) },
             descriptor.valueParameters.mapIndexed { index, desc -> parameter(index, desc, dri) },
+            descriptor.findKDoc(),
             descriptor
         )
     }
@@ -64,10 +70,10 @@ object DokkaDescriptorVisitor : DeclarationDescriptorVisitorEmptyBodies<Document
     override fun visitReceiverParameterDescriptor(
         descriptor: ReceiverParameterDescriptor,
         parent: DRI
-    ) = Parameter(parent.copy(target = 0), null, descriptor)
+    ) = Parameter(parent.copy(target = 0), null, descriptor.findKDoc(), descriptor)
 
     private fun parameter(index: Int, descriptor: ValueParameterDescriptor, parent: DRI) =
-        Parameter(parent.copy(target = index + 1), descriptor.name.asString(), descriptor)
+        Parameter(parent.copy(target = index + 1), descriptor.name.asString(), descriptor.findKDoc(), descriptor)
 
     private fun MemberScope.functions(parent: DRI): List<Function> =
         getContributedDescriptors(DescriptorKindFilter.FUNCTIONS) { true }
diff --git a/core/src/main/kotlin/Model/DocumentationNode.kt b/core/src/main/kotlin/Model/DocumentationNode.kt
index 1871e21c..48bad7eb 100644
--- a/core/src/main/kotlin/Model/DocumentationNode.kt
+++ b/core/src/main/kotlin/Model/DocumentationNode.kt
@@ -2,13 +2,14 @@ package org.jetbrains.dokka.Model
 
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.kotlin.descriptors.*
+import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag
 
 class Module(val packages: List<Package>) : DocumentationNode<Nothing>() {
-    override val dri: DRI
-        get() = DRI.topLevel
+    override val docTag: KDocTag? = null
 
-    override val children: List<Package>
-        get() = packages
+    override val dri: DRI = DRI.topLevel
+
+    override val children: List<Package> = packages
 }
 
 class Package(
@@ -18,6 +19,8 @@ class Package(
     override val classes: List<Class>
 ) : ScopeNode<Nothing>() {
     val name = dri.packageName.orEmpty()
+
+    override val docTag: KDocTag? = null
 }
 
 class Class(
@@ -26,6 +29,7 @@ class Class(
     override val functions: List<Function>,
     override val properties: List<Property>,
     override val classes: List<Class>,
+    override val docTag: KDocTag?,
     override val descriptor: ClassDescriptor
 ) : ScopeNode<ClassDescriptor>()
 
@@ -34,6 +38,7 @@ class Function(
     val name: String,
     override val receiver: Parameter?,
     val parameters: List<Parameter>,
+    override val docTag: KDocTag?,
     override val descriptor: FunctionDescriptor
 ) : CallableNode<FunctionDescriptor>() {
     override val children: List<Parameter>
@@ -44,6 +49,7 @@ class Property(
     override val dri: DRI,
     val name: String,
     override val receiver: Parameter?,
+    override val docTag: KDocTag?,
     override val descriptor: PropertyDescriptor
 ) : CallableNode<PropertyDescriptor>() {
     override val children: List<Parameter>
@@ -53,6 +59,7 @@ class Property(
 class Parameter(
     override val dri: DRI,
     val name: String?,
+    override val docTag: KDocTag?,
     override val descriptor: ParameterDescriptor
 ) : DocumentationNode<ParameterDescriptor>() {
     override val children: List<DocumentationNode<*>>
@@ -62,17 +69,25 @@ class Parameter(
 abstract class DocumentationNode<out T : DeclarationDescriptor> {
     open val descriptor: T? = null
 
+    abstract val docTag: KDocTag? // TODO: replace in the future with more robust doc-comment model
+
     abstract val dri: DRI
 
     abstract val children: List<DocumentationNode<*>>
 
     override fun toString(): String {
-        return "${javaClass.simpleName}($dri)"
+        return "${javaClass.simpleName}($dri)" + briefDocstring.takeIf { it.isNotBlank() }?.let { " [$it]"}.orEmpty()
     }
 
     override fun equals(other: Any?) = other is DocumentationNode<*> && this.dri == other.dri
 
     override fun hashCode() = dri.hashCode()
+
+    val rawDocstring: String
+        get() = docTag?.getContent().orEmpty()
+
+    val briefDocstring: String
+        get() = rawDocstring.shorten(40)
 }
 
 abstract class ScopeNode<out T : ClassOrPackageFragmentDescriptor> : DocumentationNode<T>() {
@@ -86,4 +101,8 @@ abstract class ScopeNode<out T : ClassOrPackageFragmentDescriptor> : Documentati
 
 abstract class CallableNode<out T : CallableDescriptor> : DocumentationNode<T>() {
     abstract val receiver: Parameter?
+}
+
+private fun String.shorten(maxLength: Int) = lineSequence().first().let {
+    if (it.length != length || it.length > maxLength) it.take(maxLength - 3) + "..." else it
 }
\ No newline at end of file
diff --git a/core/src/main/kotlin/Utilities/nodeDebug.kt b/core/src/main/kotlin/Utilities/nodeDebug.kt
index 423e3e5f..c7a771d8 100644
--- a/core/src/main/kotlin/Utilities/nodeDebug.kt
+++ b/core/src/main/kotlin/Utilities/nodeDebug.kt
@@ -10,15 +10,12 @@ const val LAST = '\u2517'
 fun <T : DeclarationDescriptor> DocumentationNode<T>.pretty(prefix: String = "", isLast: Boolean = true): String {
     val nextPrefix = prefix + (if (isLast) ' ' else DOWN) + ' '
 
-    return prefix + (if (isLast) LAST else BRANCH) + this.toString() + children.dropLast(1).map {
-        it.pretty(
-            nextPrefix,
-            false
-        )
-    }.plus(
-        children.lastOrNull()?.pretty(nextPrefix)
-    ).filterNotNull().takeIf { it.isNotEmpty() }?.joinToString(
-        prefix = "\n",
-        separator = ""
-    ).orEmpty() + if (children.isEmpty()) "\n" else ""
+    return prefix + (if (isLast) LAST else BRANCH) + this.toString() +
+            children.dropLast(1)
+                .map { it.pretty(nextPrefix, false) }
+                .plus(children.lastOrNull()?.pretty(nextPrefix))
+                .filterNotNull()
+                .takeIf { it.isNotEmpty() }
+                ?.joinToString(prefix = "\n", separator = "")
+                .orEmpty() + if (children.isEmpty()) "\n" else ""
 }
\ No newline at end of file
-- 
cgit