Adds includes configuration parameter to include package and module descriptions

4 files changed, 99 insertions, 0 deletions

diff --git a/plugins/base/src/main/kotlin/DokkaBase.kt b/plugins/base/src/main/kotlin/DokkaBase.kt
index 77028d53..934bb3df 100644
--- a/plugins/base/src/main/kotlin/DokkaBase.kt
+++ b/plugins/base/src/main/kotlin/DokkaBase.kt
@@ -15,6 +15,7 @@ import org.jetbrains.dokka.base.transformers.documentables.DefaultDocumentableMe
 import org.jetbrains.dokka.base.transformers.documentables.InheritorsExtractorTransformer
 import org.jetbrains.dokka.base.transformers.pages.annotations.DeprecatedStrikethroughTransformer
 import org.jetbrains.dokka.base.transformers.documentables.DocumentableVisibilityFilter
+import org.jetbrains.dokka.base.transformers.documentables.ModuleAndPackageDocumentationTransformer
 import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentConverter
 import org.jetbrains.dokka.base.transformers.pages.comments.DocTagToContentConverter
 import org.jetbrains.dokka.base.transformers.pages.merger.FallbackPageMergerStrategy
@@ -56,6 +57,10 @@ class DokkaBase : DokkaPlugin() {
         CoreExtensions.preMergeDocumentableTransformer with ActualTypealiasAdder()
     }
 
+    val modulesAndPackagesDocumentation by extending(isFallback = true) {
+        CoreExtensions.preMergeDocumentableTransformer with ModuleAndPackageDocumentationTransformer
+    }
+
     val kotlinSignatureProvider by extending(isFallback = true) {
         signatureProvider providing { ctx ->
             KotlinSignatureProvider(ctx.single(commentsToContentConverter), ctx.logger)
diff --git a/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt
new file mode 100644
index 00000000..92fa8ce4
--- /dev/null
+++ b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt
@@ -0,0 +1,81 @@
+package org.jetbrains.dokka.base.transformers.documentables
+
+import org.jetbrains.dokka.model.DModule
+import org.jetbrains.dokka.model.PlatformDependent
+import org.jetbrains.dokka.parsers.MarkdownParser
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer
+import org.jetbrains.kotlin.name.FqName
+import java.nio.file.Files
+import java.nio.file.Paths
+
+
+internal object ModuleAndPackageDocumentationTransformer : PreMergeDocumentableTransformer {
+
+    override fun invoke(original: List<DModule>, context: DokkaContext): List<DModule> {
+
+        val modulesAndPackagesDocumentation =
+            context.configuration.passesConfigurations
+                .map {
+                    Pair(it.moduleName, it.platformData) to
+                        it.includes.map { Paths.get(it) }
+                            .filter { Files.exists(it) }
+                            .flatMap {
+                                it.toFile()
+                                    .readText()
+                                    .split(Regex("(\n|^)# (?=(Module|Package))")) // Matches heading with Module/Package to split by
+                                    .filter { it.isNotEmpty() }
+                                    .map { it.split(Regex(" "), 2) } // Matches space between Module/Package and fully qualified name
+                            }.groupBy({ it[0] }, {
+                                it[1].split(Regex("\n"), 2) // Matches new line after fully qualified name
+                                    .let { it[0] to it[1].trim() }
+                            }).mapValues {
+                                it.value.toMap()
+                            }
+                }.toMap()
+
+        return original.map { module ->
+
+            val moduleDocumentation =
+                module.platformData.mapNotNull { pd ->
+                    val doc = modulesAndPackagesDocumentation[Pair(module.name, pd)]
+                    val facade = context.platforms[pd]?.facade ?:
+                        return@mapNotNull null.also { context.logger.warn("Could not find platform data for ${pd.name}") }
+                    doc?.get("Module")?.get(module.name)?.run {
+                        pd to MarkdownParser(
+                            facade,
+                            facade.moduleDescriptor
+                        ).parse(this)
+                    }
+                }.toMap()
+
+            val packagesDocumentation = module.packages.map {
+                it.name to it.platformData.mapNotNull { pd ->
+                    val doc = modulesAndPackagesDocumentation[Pair(module.name, pd)]
+                    val facade = context.platforms[pd]?.facade ?:
+                        return@mapNotNull null.also { context.logger.warn("Could not find platform data for ${pd.name}") }
+                    val descriptor = facade.resolveSession.getPackageFragment(FqName(it.name)) ?:
+                        return@mapNotNull null.also { context.logger.warn("Could not find descriptor for $") }
+                    doc?.get("Package")?.get(it.name)?.run {
+                        pd to MarkdownParser(
+                            facade,
+                            descriptor
+                        ).parse(this)
+                    }
+                }.toMap()
+            }.toMap()
+
+            module.copy(
+                documentation = module.documentation.let { PlatformDependent(it.map + moduleDocumentation) },
+                packages = module.packages.map {
+                    if(packagesDocumentation[it.name] != null)
+                        it.copy(documentation = it.documentation.let { value ->
+                            PlatformDependent(value.map + packagesDocumentation[it.name]!!)
+                        })
+                    else
+                        it
+                }
+            )
+        }
+    }
+}
diff --git a/plugins/base/src/main/kotlin/transformers/pages/sourcelinks/SourceLinksTransformer.kt b/plugins/base/src/main/kotlin/transformers/pages/sourcelinks/SourceLinksTransformer.kt
new file mode 100644
index 00000000..e6ab7b5e
--- /dev/null
+++ b/plugins/base/src/main/kotlin/transformers/pages/sourcelinks/SourceLinksTransformer.kt
@@ -0,0 +1,10 @@
+package org.jetbrains.dokka.base.transformers.pages.sourcelinks
+
+import org.jetbrains.dokka.pages.RootPageNode
+import org.jetbrains.dokka.transformers.pages.PageTransformer
+
+object SourceLinksTransformer : PageTransformer {
+    override fun invoke(input: RootPageNode): RootPageNode {
+        TODO("not implemented") //To change body of created functions use File | Settings | File Templates.
+    }
+}
\ No newline at end of file
diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
index 3fcd07b3..8942991e 100644
--- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
+++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
@@ -64,6 +64,7 @@ open class DefaultPageCreator(
 
     protected open fun contentForModule(m: DModule) = contentBuilder.contentFor(m) {
         header(1) { text(m.name) }
+        +contentForComments(m)
         block("Packages", 2, ContentKind.Packages, m.packages, m.platformData.toSet()) {
             link(it.name, it.dri)
         }
@@ -74,7 +75,9 @@ open class DefaultPageCreator(
     protected open fun contentForPackage(p: DPackage) = contentBuilder.contentFor(p) {
         group(p.dri, p.platformData.toSet(), ContentKind.Packages) {
             header(1) { text("Package ${p.name}") }
+            +contentForComments(p)
         }
+        header(1) { text("Package ${p.name}") }
         +contentForScope(p, p.dri, p.platformData)
         block("Type aliases", 2, ContentKind.TypeAliases, p.typealiases, p.platformData.toSet()) {
             link(it.name, it.dri)