Minor readability improvement in ModuleAndPackageDocumentationTransformer.kt

2 files changed, 27 insertions, 12 deletions

diff --git a/plugins/base/src/main/kotlin/allModulePage/MultimodulePageCreator.kt b/plugins/base/src/main/kotlin/allModulePage/MultimodulePageCreator.kt
index dab06343..e8c6f02d 100644
--- a/plugins/base/src/main/kotlin/allModulePage/MultimodulePageCreator.kt
+++ b/plugins/base/src/main/kotlin/allModulePage/MultimodulePageCreator.kt
@@ -12,6 +12,7 @@ import org.jetbrains.dokka.base.resolvers.local.MultimoduleLocationProvider.Comp
 import org.jetbrains.dokka.base.transformers.pages.comments.DocTagToContentConverter
 import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder
 import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.doc.DocTag
 import org.jetbrains.dokka.model.doc.DocumentationNode
 import org.jetbrains.dokka.model.doc.P
 import org.jetbrains.dokka.pages.*
@@ -20,7 +21,7 @@ import org.jetbrains.dokka.plugability.querySingle
 import org.jetbrains.dokka.transformers.pages.PageCreator
 import org.jetbrains.dokka.utilities.DokkaLogger
 
-class MultimodulePageCreator (
+class MultimodulePageCreator(
     private val context: DokkaContext,
 ) : PageCreator {
     private val logger: DokkaLogger = context.logger
@@ -71,16 +72,29 @@ class MultimodulePageCreator (
 
     private fun getDisplayedModuleDocumentation(module: DokkaModuleDescription): P? {
         val parsingContext = ModuleAndPackageDocumentationParsingContext(logger)
-        return module.includes
+
+        val documentationFragment = module.includes
             .flatMap { include -> parseModuleAndPackageDocumentationFragments(include) }
-            .map { fragment -> parseModuleAndPackageDocumentation(parsingContext, fragment) }
-            .firstOrNull { documentation -> documentation.classifier == Module && documentation.name == module.name }
-            ?.documentation?.children.orEmpty()
-            .flatMap { it.root.children }
-            .filterIsInstance<P>()
-            .firstOrNull()
+            .firstOrNull { fragment -> fragment.classifier == Module && fragment.name == module.name }
+            ?: return null
+
+        val moduleDocumentation = parseModuleAndPackageDocumentation(parsingContext, documentationFragment)
+        return moduleDocumentation.documentation.firstParagraph()
     }
 
-    private fun DocumentationNode.firstParagraph() =
-        this.children.flatMap { it.root.children }.filterIsInstance<P>().firstOrNull()
+    private fun DocumentationNode.firstParagraph(): P? =
+        this.children
+            .map { it.root }
+            .mapNotNull { it.firstParagraph() }
+            .firstOrNull()
+
+    /**
+     * @return The very first, most inner paragraph. If any [P] is wrapped inside another [P], the inner one
+     * is preferred.
+     */
+    private fun DocTag.firstParagraph(): P? {
+        val firstChildParagraph = children.mapNotNull { it.firstParagraph() }.firstOrNull()
+        return if (firstChildParagraph == null && this is P) this
+        else firstChildParagraph
+    }
 }
diff --git a/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt
index bf6579af..2b2a3f03 100644
--- a/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt
+++ b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt
@@ -2,6 +2,7 @@ package org.jetbrains.dokka.base.transformers.documentables
 
 import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
 import org.jetbrains.dokka.model.DModule
+import org.jetbrains.dokka.model.SourceSetDependent
 import org.jetbrains.dokka.model.doc.DocumentationNode
 import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer
 
@@ -22,8 +23,8 @@ internal class ModuleAndPackageDocumentationTransformer(
         }
     }
 
-    private operator fun Map<DokkaSourceSet, DocumentationNode>.plus(
-        other: Map<DokkaSourceSet, DocumentationNode>
+    private operator fun SourceSetDependent<DocumentationNode>.plus(
+        other: SourceSetDependent<DocumentationNode>
     ): Map<DokkaSourceSet, DocumentationNode> =
         (asSequence() + other.asSequence())
             .distinct()