From 3b200cf10e0c50c2eee4b9da3f7039d678fa4aad Mon Sep 17 00:00:00 2001
From: Paweł Marks <pmarks@virtuslab.com>
Date: Sun, 16 Feb 2020 23:20:17 +0100
Subject: Renames DocumentationToPagesTranslatero and moves its implementation
 to base plugin

---
 plugins/base/src/main/kotlin/DokkaBase.kt          |   9 +-
 .../DefaultDocumentablesToPageTranslator.kt        |  22 +++
 .../transformers/documentables/PageBuilder.kt      | 159 +++++++++++++++
 .../documentables/PageContentBuilder.kt            | 217 +++++++++++++++++++++
 .../src/main/kotlin/KotlinAsJavaPageBuilder.kt     |   2 +
 .../main/kotlin/KotlinAsJavaPageContentBuilder.kt  |  17 +-
 .../src/main/kotlin/KotlinAsJavaPlugin.kt          |   6 +-
 7 files changed, 420 insertions(+), 12 deletions(-)
 create mode 100644 plugins/base/src/main/kotlin/transformers/documentables/DefaultDocumentablesToPageTranslator.kt
 create mode 100644 plugins/base/src/main/kotlin/transformers/documentables/PageBuilder.kt
 create mode 100644 plugins/base/src/main/kotlin/transformers/documentables/PageContentBuilder.kt

(limited to 'plugins')

diff --git a/plugins/base/src/main/kotlin/DokkaBase.kt b/plugins/base/src/main/kotlin/DokkaBase.kt
index b18e2ad5..34c0ffae 100644
--- a/plugins/base/src/main/kotlin/DokkaBase.kt
+++ b/plugins/base/src/main/kotlin/DokkaBase.kt
@@ -3,14 +3,19 @@ package org.jetbrains.dokka.base
 import org.jetbrains.dokka.CoreExtensions
 import org.jetbrains.dokka.base.transformers.descriptors.DefaultDescriptorToDocumentationTranslator
 import org.jetbrains.dokka.base.transformers.documentables.DefaultDocumentableMerger
+import org.jetbrains.dokka.base.transformers.documentables.DefaultDocumentablesToPageTranslator
 import org.jetbrains.dokka.plugability.DokkaPlugin
 
 class DokkaBase: DokkaPlugin() {
-    val defaultDescriptorToDocumentationTranslator by extending(isFallback = true) {
+    val descriptorToDocumentationTranslator by extending(isFallback = true) {
         CoreExtensions.descriptorToDocumentationTranslator providing ::DefaultDescriptorToDocumentationTranslator
     }
 
-    val defaultDocumentableMerger by extending(isFallback = true) {
+    val documentableMerger by extending(isFallback = true) {
         CoreExtensions.documentableMerger with DefaultDocumentableMerger
     }
+
+    val documentablesToPageTranslator by extending(isFallback = true) {
+        CoreExtensions.documentablesToPageTranslator with DefaultDocumentablesToPageTranslator
+    }
 }
\ No newline at end of file
diff --git a/plugins/base/src/main/kotlin/transformers/documentables/DefaultDocumentablesToPageTranslator.kt b/plugins/base/src/main/kotlin/transformers/documentables/DefaultDocumentablesToPageTranslator.kt
new file mode 100644
index 00000000..90f8e2d7
--- /dev/null
+++ b/plugins/base/src/main/kotlin/transformers/documentables/DefaultDocumentablesToPageTranslator.kt
@@ -0,0 +1,22 @@
+package org.jetbrains.dokka.base.transformers.documentables
+
+import org.jetbrains.dokka.CoreExtensions
+import org.jetbrains.dokka.model.Module
+import org.jetbrains.dokka.pages.ModulePageNode
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.transformers.documentation.DocumentablesToPageTranslator
+
+
+object DefaultDocumentablesToPageTranslator : DocumentablesToPageTranslator {
+    override fun invoke(module: Module, context: DokkaContext): ModulePageNode =
+        DefaultPageBuilder { node, kind, operation ->
+            DefaultPageContentBuilder.group(
+                setOf(node.dri),
+                node.platformData,
+                kind,
+                context.single(CoreExtensions.commentsToContentConverter),
+                context.logger,
+                operation
+            )
+        }.pageForModule(module)
+}
\ No newline at end of file
diff --git a/plugins/base/src/main/kotlin/transformers/documentables/PageBuilder.kt b/plugins/base/src/main/kotlin/transformers/documentables/PageBuilder.kt
new file mode 100644
index 00000000..29f39c73
--- /dev/null
+++ b/plugins/base/src/main/kotlin/transformers/documentables/PageBuilder.kt
@@ -0,0 +1,159 @@
+package org.jetbrains.dokka.base.transformers.documentables
+
+import org.jetbrains.dokka.model.*
+import org.jetbrains.dokka.model.Enum
+import org.jetbrains.dokka.model.Function
+import org.jetbrains.dokka.model.doc.TagWrapper
+import org.jetbrains.dokka.pages.*
+
+open class DefaultPageBuilder(
+    override val rootContentGroup: RootContentBuilder
+) : PageBuilder {
+
+    override fun pageForModule(m: Module): ModulePageNode =
+        ModulePageNode(m.name.ifEmpty { "root" }, contentForModule(m), m, m.packages.map { pageForPackage(it) })
+
+    override fun pageForPackage(p: Package) =
+        PackagePageNode(p.name, contentForPackage(p), setOf(p.dri), p,
+            p.classlikes.map { pageForClasslike(it) } +
+                    p.functions.map { pageForMember(it) })
+
+    override fun pageForClasslike(c: Classlike): ClasslikePageNode {
+        val constructors = when (c) {
+            is Class -> c.constructors
+            is Enum -> c.constructors
+            else -> emptyList()
+        }
+
+        return ClasslikePageNode(c.name, contentForClasslike(c), setOf(c.dri), c,
+            constructors.map { pageForMember(it) } +
+                    c.classlikes.map { pageForClasslike(it) } +
+                    c.functions.map { pageForMember(it) })
+    }
+
+    override fun pageForMember(m: CallableNode): MemberPageNode =
+        when (m) {
+            is Function ->
+                MemberPageNode(m.name, contentForFunction(m), setOf(m.dri), m)
+            else -> throw IllegalStateException("$m should not be present here")
+        }
+
+    protected open fun group(node: Documentable, content: PageContentBuilderFunction) =
+        rootContentGroup(node, ContentKind.Main, content)
+
+    protected open fun contentForModule(m: Module) = group(m) {
+        header(1) { text("root") }
+        block("Packages", 2, ContentKind.Packages, m.packages, m.platformData) {
+            link(it.name, it.dri)
+        }
+        text("Index\n")
+        text("Link to allpage here")
+    }
+
+    protected open fun contentForPackage(p: Package) = group(p) {
+        header(1) { text("Package ${p.name}") }
+        block("Types", 2, ContentKind.Properties, p.classlikes, p.platformData) {
+            link(it.name, it.dri)
+            text(it.briefDocTagString)
+        }
+        block("Functions", 2, ContentKind.Functions, p.functions, p.platformData) {
+            link(it.name, it.dri)
+            signature(it)
+            text(it.briefDocTagString)
+        }
+    }
+
+    open fun contentForClasslike(c: Classlike): ContentGroup = when (c) {
+        is Class -> contentForClass(c)
+        is Enum -> contentForEnum(c)
+        else -> throw IllegalStateException("$c should not be present here")
+    }
+
+    protected fun contentForClass(c: Class) = group(c) {
+        header(1) { text(c.name) }
+
+        c.inherited.takeIf { it.isNotEmpty() }?.let {
+            header(2) { text("SuperInterfaces") }
+            linkTable(it)
+        }
+        contentForComments(c)
+        block("Constructors", 2, ContentKind.Functions, c.constructors, c.platformData) {
+            link(it.name, it.dri)
+            signature(it)
+            text(it.briefDocTagString)
+        }
+        block("Functions", 2, ContentKind.Functions, c.functions, c.platformData) {
+            link(it.name, it.dri)
+            signature(it)
+            text(it.briefDocTagString)
+        }
+        block("Properties", 2, ContentKind.Properties, c.properties, c.platformData) {
+            link(it.name, it.dri)
+            text(it.briefDocTagString)
+
+        }
+    }
+
+    fun contentForEnum(c: Enum): ContentGroup = group(c) {
+        header(1) { text("enum ${c.name}") }
+
+        block("Entries", 2, ContentKind.Properties, c.entries, c.platformData) { entry ->
+            link(entry.name, entry.dri)
+            contentForComments(entry)
+        }
+
+        c.inherited.takeIf { it.isNotEmpty() }?.let {
+            header(2) { text("SuperInterfaces") }
+            linkTable(it)
+        }
+        contentForComments(c)
+        block("Constructors", 2, ContentKind.Functions, c.constructors, c.platformData) {
+            link(it.name, it.dri)
+            signature(it)
+            text(it.briefDocTagString)
+        }
+        block("Functions", 2, ContentKind.Functions, c.functions, c.platformData) {
+            link(it.name, it.dri)
+            signature(it)
+            text(it.briefDocTagString)
+        }
+        block("Properties", 2, ContentKind.Properties, c.properties, c.platformData) {
+            link(it.name, it.dri)
+            text(it.briefDocTagString)
+        }
+    }
+
+    private fun PageContentBuilder.contentForComments(d: Documentable) =
+        d.platformInfo.forEach { platformInfo ->
+            platformInfo.documentationNode.children.forEach {
+                header(3) {
+                    text(it.toHeaderString())
+                    text(" [${platformInfo.platformData.joinToString(", ") { it.platformType.name }}]")
+                }
+                comment(it.root)
+                text("\n")
+            }
+        }
+
+    private fun contentForFunction(f: Function) = group(f) {
+        header(1) { text(f.name) }
+        signature(f)
+        contentForComments(f)
+        block("Parameters", 2, ContentKind.Parameters, f.children, f.platformData) {
+            text(it.name ?: "<receiver>")
+            it.platformInfo.forEach { it.documentationNode.children.forEach { comment(it.root) } }
+        }
+    }
+
+    private fun TagWrapper.toHeaderString() = this.javaClass.toGenericString().split('.').last()
+}
+
+typealias RootContentBuilder = (Documentable, Kind, PageContentBuilderFunction) -> ContentGroup
+
+interface PageBuilder {
+    val rootContentGroup: RootContentBuilder
+    fun pageForModule(m: Module): ModulePageNode
+    fun pageForPackage(p: Package): PackagePageNode
+    fun pageForMember(m: CallableNode): MemberPageNode
+    fun pageForClasslike(c: Classlike): ClasslikePageNode
+}
\ No newline at end of file
diff --git a/plugins/base/src/main/kotlin/transformers/documentables/PageContentBuilder.kt b/plugins/base/src/main/kotlin/transformers/documentables/PageContentBuilder.kt
new file mode 100644
index 00000000..809b97a0
--- /dev/null
+++ b/plugins/base/src/main/kotlin/transformers/documentables/PageContentBuilder.kt
@@ -0,0 +1,217 @@
+package org.jetbrains.dokka.base.transformers.documentables
+
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.Documentable
+import org.jetbrains.dokka.model.Function
+import org.jetbrains.dokka.model.TypeWrapper
+import org.jetbrains.dokka.model.doc.DocTag
+import org.jetbrains.dokka.pages.*
+import org.jetbrains.dokka.utilities.DokkaLogger
+
+open class DefaultPageContentBuilder(
+    protected val dri: Set<DRI>,
+    protected val platformData: Set<PlatformData>,
+    protected val kind: Kind,
+    protected val commentsConverter: CommentsToContentConverter,
+    val logger: DokkaLogger,
+    protected val styles: Set<Style> = emptySet(),
+    protected val extras: Set<Extra> = emptySet()
+) : PageContentBuilder {
+    protected val contents = mutableListOf<ContentNode>()
+
+    protected fun createText(text: String, kind: Kind = ContentKind.Symbol) =
+        ContentText(text, DCI(dri, kind), platformData, styles, extras)
+
+    protected fun build() = ContentGroup(
+        contents.toList(),
+        DCI(dri, kind),
+        platformData,
+        styles,
+        extras
+    )
+
+    override fun header(level: Int, block: PageContentBuilderFunction) {
+        contents += ContentHeader(level, group(ContentKind.Symbol, block))
+    }
+
+    override fun text(text: String, kind: Kind) {
+        contents += createText(text, kind)
+    }
+
+    protected fun signature(f: Function, block: PageContentBuilderFunction) {
+        contents += group(setOf(f.dri), f.platformData, ContentKind.Symbol, block)
+    }
+
+    override fun signature(f: Function) = signature(f) {
+        text("fun ")
+        f.receiver?.also {
+            type(it.type)
+            text(".")
+        }
+        link(f.name, f.dri)
+        text("(")
+        list(f.parameters) {
+            link(it.name!!, it.dri)
+            text(": ")
+            type(it.type)
+        }
+        text(")")
+        val returnType = f.returnType
+        if (!f.isConstructor && returnType != null &&
+            returnType.constructorFqName != Unit::class.qualifiedName
+        ) {
+            text(": ")
+            type(returnType)
+        }
+    }
+
+    override fun linkTable(elements: List<DRI>) {
+        contents += ContentTable(
+            emptyList(),
+            elements.map { group(dri, platformData, ContentKind.Classes) { link(it.classNames ?: "", it) } },
+            DCI(dri, kind),
+            platformData, styles, extras
+        )
+    }
+
+    override fun <T : Documentable> block(
+        name: String,
+        level: Int,
+        kind: Kind,
+        elements: Iterable<T>,
+        platformData: Set<PlatformData>,
+        operation: PageContentBuilder.(T) -> Unit
+    ) {
+        header(level) { text(name) }
+
+        contents += ContentTable(
+            emptyList(),
+            elements.map { group(setOf(it.dri), it.platformData, kind) { operation(it) } },
+            DCI(dri, kind),
+            platformData, styles, extras
+        )
+    }
+
+    override fun <T> list(
+        elements: List<T>,
+        prefix: String,
+        suffix: String,
+        separator: String,
+        operation: PageContentBuilder.(T) -> Unit
+    ) {
+        if (elements.isNotEmpty()) {
+            if (prefix.isNotEmpty()) text(prefix)
+            elements.dropLast(1).forEach {
+                operation(it)
+                text(separator)
+            }
+            operation(elements.last())
+            if (suffix.isNotEmpty()) text(suffix)
+        }
+    }
+
+    override fun link(text: String, address: DRI, kind: Kind) {
+        contents += ContentDRILink(
+            listOf(createText(text)),
+            address,
+            DCI(dri, kind),
+            platformData
+        )
+    }
+
+    override fun link(address: DRI, kind: Kind, block: PageContentBuilderFunction) {
+        contents += ContentDRILink(
+            group(ContentKind.Main, block).children,
+            address,
+            DCI(dri, kind),
+            platformData
+        )
+    }
+
+    override fun comment(docTag: DocTag) {
+        contents += group(ContentKind.Comment) {
+            with(this as DefaultPageContentBuilder) {
+                contents += commentsConverter.buildContent(
+                    docTag,
+                    DCI(dri, ContentKind.Comment),
+                    platformData
+                )
+            }
+        }
+    }
+
+    fun group(kind: Kind, block: PageContentBuilderFunction): ContentGroup =
+        group(dri, platformData, kind, block)
+
+    override fun group(
+        dri: Set<DRI>,
+        platformData: Set<PlatformData>,
+        kind: Kind,
+        block: PageContentBuilderFunction
+    ): ContentGroup = group(dri, platformData, kind, commentsConverter, logger, block)
+
+    companion object {
+        fun group(
+            dri: Set<DRI>,
+            platformData: Set<PlatformData>,
+            kind: Kind,
+            commentsConverter: CommentsToContentConverter,
+            logger: DokkaLogger,
+            block: PageContentBuilderFunction
+        ): ContentGroup =
+            DefaultPageContentBuilder(dri, platformData, kind, commentsConverter, logger).apply(block).build()
+    }
+}
+
+
+fun PageContentBuilder.type(t: TypeWrapper) {
+    if (t.constructorNamePathSegments.isNotEmpty() && t.dri != null)
+        link(t.constructorNamePathSegments.last(), t.dri!!)
+    else if (t.constructorNamePathSegments.isNotEmpty() && t.dri == null)
+        text(t.toString())
+    else (this as? DefaultPageContentBuilder)?.let {
+        logger.error("type $t cannot be resolved")
+        text("???")
+    }
+    list(t.arguments, prefix = "<", suffix = ">") {
+        type(it)
+    }
+}
+
+typealias PageContentBuilderFunction = PageContentBuilder.() -> Unit
+
+@DslMarker
+annotation class ContentMarker
+
+@ContentMarker
+interface PageContentBuilder {
+    fun group(
+        dri: Set<DRI>,
+        platformData: Set<PlatformData>,
+        kind: Kind, block: PageContentBuilderFunction
+    ): ContentGroup
+
+    fun text(text: String, kind: Kind = ContentKind.Symbol)
+    fun signature(f: Function)
+    fun link(text: String, address: DRI, kind: Kind = ContentKind.Symbol)
+    fun link(address: DRI, kind: Kind = ContentKind.Symbol, block: PageContentBuilderFunction)
+    fun linkTable(elements: List<DRI>)
+    fun comment(docTag: DocTag)
+    fun header(level: Int, block: PageContentBuilderFunction)
+    fun <T> list(
+        elements: List<T>,
+        prefix: String = "",
+        suffix: String = "",
+        separator: String = ",",
+        operation: PageContentBuilder.(T) -> Unit
+    )
+
+    fun <T : Documentable> block(
+        name: String,
+        level: Int,
+        kind: Kind,
+        elements: Iterable<T>,
+        platformData: Set<PlatformData>,
+        operation: PageContentBuilder.(T) -> Unit
+    )
+}
\ No newline at end of file
diff --git a/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPageBuilder.kt b/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPageBuilder.kt
index 6fe10ce1..d4dfdaea 100644
--- a/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPageBuilder.kt
+++ b/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPageBuilder.kt
@@ -1,5 +1,7 @@
 package org.jetbrains.dokka.kotlinAsJava
 
+import org.jetbrains.dokka.base.transformers.documentables.DefaultPageBuilder
+import org.jetbrains.dokka.base.transformers.documentables.RootContentBuilder
 import org.jetbrains.dokka.kotlinAsJava.conversions.asJava
 import org.jetbrains.dokka.kotlinAsJava.conversions.asStatic
 import org.jetbrains.dokka.kotlinAsJava.conversions.withClass
diff --git a/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPageContentBuilder.kt b/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPageContentBuilder.kt
index a5d0bd33..02e6ff82 100644
--- a/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPageContentBuilder.kt
+++ b/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPageContentBuilder.kt
@@ -1,5 +1,8 @@
 package org.jetbrains.dokka.kotlinAsJava
 
+import org.jetbrains.dokka.base.transformers.documentables.DefaultPageContentBuilder
+import org.jetbrains.dokka.base.transformers.documentables.PageContentBuilderFunction
+import org.jetbrains.dokka.base.transformers.documentables.type
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.Function
 import org.jetbrains.dokka.model.JavaTypeWrapper
@@ -7,13 +10,13 @@ import org.jetbrains.dokka.pages.*
 import org.jetbrains.dokka.utilities.DokkaLogger
 
 class KotlinAsJavaPageContentBuilder(
-    private val dri: Set<DRI>,
-    private val platformData: Set<PlatformData>,
-    private val kind: Kind,
-    private val commentsConverter: CommentsToContentConverter,
-    override val logger: DokkaLogger,
-    private val styles: Set<Style> = emptySet(),
-    private val extras: Set<Extra> = emptySet()
+    dri: Set<DRI>,
+    platformData: Set<PlatformData>,
+    kind: Kind,
+    commentsConverter: CommentsToContentConverter,
+    logger: DokkaLogger,
+    styles: Set<Style> = emptySet(),
+    extras: Set<Extra> = emptySet()
 ) : DefaultPageContentBuilder(dri, platformData, kind, commentsConverter, logger, styles, extras) {
 
     override fun signature(f: Function) = signature(f) {
diff --git a/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt b/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt
index dd95f00e..f8a25aca 100644
--- a/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt
+++ b/plugins/kotlin-as-java/src/main/kotlin/KotlinAsJavaPlugin.kt
@@ -7,7 +7,7 @@ import org.jetbrains.dokka.model.Module
 import org.jetbrains.dokka.pages.ModulePageNode
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.DokkaPlugin
-import org.jetbrains.dokka.transformers.documentation.DocumentationToPageTranslator
+import org.jetbrains.dokka.transformers.documentation.DocumentablesToPageTranslator
 import org.jetbrains.kotlin.descriptors.DeclarationDescriptor
 
 class KotlinAsJavaPlugin : DokkaPlugin() {
@@ -15,7 +15,7 @@ class KotlinAsJavaPlugin : DokkaPlugin() {
         CoreExtensions.descriptorToDocumentationTranslator providing ::KotlinAsJavaDescriptorToDocumentationTranslator
     }
     val kotlinAsJavaDocumentableToPageTranslator by extending {
-        CoreExtensions.documentationToPageTranslator with KotlinAsJavaDocumentationToPageTranslator
+        CoreExtensions.documentablesToPageTranslator with KotlinAsJavaDocumentationToPageTranslator
     }
 }
 
@@ -26,7 +26,7 @@ object DescriptorCache {
     operator fun get(dri: DRI): DeclarationDescriptor? = cache[dri]
 }
 
-object KotlinAsJavaDocumentationToPageTranslator : DocumentationToPageTranslator {
+object KotlinAsJavaDocumentationToPageTranslator : DocumentablesToPageTranslator {
     override fun invoke(module: Module, context: DokkaContext): ModulePageNode =
         KotlinAsJavaPageBuilder { node, kind, operation ->
             KotlinAsJavaPageContentBuilder.group(
-- 
cgit