Fix merging documentations of modules and packages (#1480)

* Fix merging documentations of modules and packages

* Adjust doctag to new API

Co-authored-by: Marcin Aman <marcin.aman@gmail.com>

3 files changed, 96 insertions, 2 deletions

diff --git a/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationReader.kt b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationReader.kt
index e126d05f..6e26377e 100644
--- a/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationReader.kt
+++ b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationReader.kt
@@ -12,7 +12,8 @@ import org.jetbrains.dokka.base.parsers.moduleAndPackage.parseModuleAndPackageDo
 import org.jetbrains.dokka.model.DModule
 import org.jetbrains.dokka.model.DPackage
 import org.jetbrains.dokka.model.SourceSetDependent
-import org.jetbrains.dokka.model.doc.DocumentationNode
+import org.jetbrains.dokka.model.doc.*
+import org.jetbrains.dokka.model.doc.Deprecated
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.utilities.associateWithNotNull
 
@@ -51,7 +52,8 @@ private class ContextModuleAndPackageDocumentationReader(
             when (documentations.size) {
                 0 -> null
                 1 -> documentations.single().documentation
-                else -> DocumentationNode(documentations.flatMap { it.documentation.children })
+                else -> DocumentationNode(documentations.flatMap { it.documentation.children }
+                    .mergeDocumentationNodes())
             }
         }
     }
@@ -74,4 +76,31 @@ private class ContextModuleAndPackageDocumentationReader(
             fragment.classifier == Classifier.Package && fragment.canonicalPackageName == pkg.dri.packageName
         }
     }
+
+    private fun List<TagWrapper>.mergeDocumentationNodes(): List<TagWrapper> =
+        groupBy { it::class }.values.map {
+            it.reduce { acc, tagWrapper ->
+                val newRoot = CustomDocTag(
+                    acc.children + tagWrapper.children,
+                    name = (tagWrapper as? NamedTagWrapper)?.name.orEmpty()
+                )
+                when (acc) {
+                    is See -> acc.copy(newRoot)
+                    is Param -> acc.copy(newRoot)
+                    is Throws -> acc.copy(newRoot)
+                    is Sample -> acc.copy(newRoot)
+                    is Property -> acc.copy(newRoot)
+                    is CustomTagWrapper -> acc.copy(newRoot)
+                    is Description -> acc.copy(newRoot)
+                    is Author -> acc.copy(newRoot)
+                    is Version -> acc.copy(newRoot)
+                    is Since -> acc.copy(newRoot)
+                    is Return -> acc.copy(newRoot)
+                    is Receiver -> acc.copy(newRoot)
+                    is Constructor -> acc.copy(newRoot)
+                    is Deprecated -> acc.copy(newRoot)
+                    is org.jetbrains.dokka.model.doc.Suppress -> acc.copy(newRoot)
+                }
+            }
+        }
 }
diff --git a/plugins/base/src/test/kotlin/linkableContent/LinkableContentTest.kt b/plugins/base/src/test/kotlin/linkableContent/LinkableContentTest.kt
index 38c7569a..7e8bde49 100644
--- a/plugins/base/src/test/kotlin/linkableContent/LinkableContentTest.kt
+++ b/plugins/base/src/test/kotlin/linkableContent/LinkableContentTest.kt
@@ -312,4 +312,66 @@ class LinkableContentTest : AbstractCoreTest() {
         }
 
     }
+
+    @Test
+    fun `Include module with description parted in two files`() {
+
+        val testDataDir = getTestDataDir("multiplatform/basicMultiplatformTest").toAbsolutePath()
+        val includesDir = getTestDataDir("linkable/includes").toAbsolutePath()
+
+        val configuration = dokkaConfiguration {
+            moduleName = "example"
+            sourceSets {
+                val common = sourceSet {
+                    name = "common"
+                    displayName = "common"
+                    analysisPlatform = "common"
+                    sourceRoots = listOf(Paths.get("$testDataDir/commonMain/kotlin").toString())
+                }
+                val jvmAndJsSecondCommonMain = sourceSet {
+                    name = "jvmAndJsSecondCommonMain"
+                    displayName = "jvmAndJsSecondCommonMain"
+                    analysisPlatform = "common"
+                    dependentSourceSets = setOf(common.value.sourceSetID)
+                    sourceRoots = listOf(Paths.get("$testDataDir/jvmAndJsSecondCommonMain/kotlin").toString())
+                }
+                val js = sourceSet {
+                    name = "js"
+                    displayName = "js"
+                    analysisPlatform = "js"
+                    dependentSourceSets = setOf(common.value.sourceSetID, jvmAndJsSecondCommonMain.value.sourceSetID)
+                    sourceRoots = listOf(Paths.get("$testDataDir/jsMain/kotlin").toString())
+                    includes = listOf(Paths.get("$includesDir/include2.md").toString())
+                }
+                val jvm = sourceSet {
+                    name = "jvm"
+                    displayName = "jvm"
+                    analysisPlatform = "jvm"
+                    dependentSourceSets = setOf(common.value.sourceSetID, jvmAndJsSecondCommonMain.value.sourceSetID)
+                    sourceRoots = listOf(Paths.get("$testDataDir/jvmMain/kotlin").toString())
+                    includes = listOf(
+                        Paths.get("$includesDir/include1.md").toString(),
+                        Paths.get("$includesDir/include11.md").toString()
+                    )
+                }
+            }
+        }
+
+        testFromData(configuration) {
+            documentablesMergingStage = {
+                it.documentation.entries.single {
+                    it.key.displayName == "jvm"
+                }.value.run {
+                    Assertions.assertNotNull(dfs {
+                        (it as? Text)?.body == "This is second JVM documentation for module example"
+                    })
+
+                    Assertions.assertNotNull(dfs {
+                        (it as? Text)?.body == "This is JVM documentation for module example"
+                    })
+                }
+            }
+        }
+
+    }
 }
diff --git a/plugins/base/src/test/resources/linkable/includes/include11.md b/plugins/base/src/test/resources/linkable/includes/include11.md
new file mode 100644
index 00000000..fa27b23d
--- /dev/null
+++ b/plugins/base/src/test/resources/linkable/includes/include11.md
@@ -0,0 +1,3 @@
+# Module example
+
+This is second JVM documentation for module example