From a465b3198f23bfe95b0f27621f597b09e5e5499b Mon Sep 17 00:00:00 2001
From: "sebastian.sellmair" <sebastian.sellmair@jetbrains.com>
Date: Mon, 10 Aug 2020 14:28:18 +0200
Subject: Add documentation to DokkaMultiModuleFileLayout

---
 .../dokka/gradle/DokkaMultiModuleFileLayout.kt     | 36 +++++++++++++++++-----
 .../dokka/gradle/DokkaMultiModuleFileLayoutTest.kt |  6 ++--
 .../dokka/gradle/DokkaMultiModuleTaskTest.kt       |  2 +-
 3 files changed, 32 insertions(+), 12 deletions(-)

diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayout.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayout.kt
index 8cca98d5..bb48ba2a 100644
--- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayout.kt
+++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayout.kt
@@ -2,17 +2,39 @@ package org.jetbrains.dokka.gradle
 
 import java.io.File
 
+/**
+ * @see DokkaMultiModuleFileLayout.targetChildOutputDirectory
+ * @see NoCopy
+ * @see CompactInParent
+ */
 interface DokkaMultiModuleFileLayout {
-    fun targetChildOutputDirectory(parent: AbstractDokkaParentTask, child: AbstractDokkaTask): File
 
+    /**
+     * @param parent: The [DokkaMultiModuleTask] that is initiating a composite documentation run
+     * @param child: Some child task registered in [parent]
+     * @return The target output directory of the [child] dokka task referenced by [parent]. This should
+     * be unique for all registered child tasks.
+     */
+    fun targetChildOutputDirectory(parent: DokkaMultiModuleTask, child: AbstractDokkaTask): File
+
+    /**
+     * Will link to the original [AbstractDokkaTask.outputDirectory]. This requires no copying of the output files.
+     */
     object NoCopy : DokkaMultiModuleFileLayout {
-        override fun targetChildOutputDirectory(parent: AbstractDokkaParentTask, child: AbstractDokkaTask): File {
+        override fun targetChildOutputDirectory(parent: DokkaMultiModuleTask, child: AbstractDokkaTask): File {
             return child.outputDirectory.getSafe()
         }
     }
 
+    /**
+     * Will point to a subfolder inside the output directory of the parent.
+     * The subfolder will follow the structure of the gradle project structure
+     * e.g.
+     * :parentProject:firstAncestor:secondAncestor will be be resolved to
+     * {parent output directory}/firstAncestor/secondAncestor
+     */
     object CompactInParent : DokkaMultiModuleFileLayout {
-        override fun targetChildOutputDirectory(parent: AbstractDokkaParentTask, child: AbstractDokkaTask): File {
+        override fun targetChildOutputDirectory(parent: DokkaMultiModuleTask, child: AbstractDokkaTask): File {
             val relativeProjectPath = parent.project.relativeProjectPath(child.project.path)
             val relativeFilePath = relativeProjectPath.replace(":", File.separator)
             check(!File(relativeFilePath).isAbsolute) { "Unexpected absolute path $relativeFilePath" }
@@ -29,14 +51,12 @@ internal fun DokkaMultiModuleTask.targetChildOutputDirectory(
 
 internal fun DokkaMultiModuleTask.copyChildOutputDirectories() {
     childDokkaTasks.forEach { child ->
-        fileLayout.copyChildOutputDirectory(this, child)
+        this.copyChildOutputDirectory(child)
     }
 }
 
-internal fun DokkaMultiModuleFileLayout.copyChildOutputDirectory(
-    parent: AbstractDokkaParentTask, child: AbstractDokkaTask
-) {
-    val targetChildOutputDirectory = parent.project.file(targetChildOutputDirectory(parent, child))
+internal fun DokkaMultiModuleTask.copyChildOutputDirectory(child: AbstractDokkaTask) {
+    val targetChildOutputDirectory = project.file(fileLayout.targetChildOutputDirectory(this, child))
     val sourceChildOutputDirectory = child.outputDirectory.getSafe()
 
     if (!sourceChildOutputDirectory.exists()) {
diff --git a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayoutTest.kt b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayoutTest.kt
index 36abacfc..951e292f 100644
--- a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayoutTest.kt
+++ b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayoutTest.kt
@@ -55,12 +55,12 @@ class DokkaMultiModuleFileLayoutTest {
         subFolder.mkdirs()
         subFolder.resolve("other.file").writeText("other text")
 
-        val layout = object : DokkaMultiModuleFileLayout {
-            override fun targetChildOutputDirectory(parent: AbstractDokkaParentTask, child: AbstractDokkaTask): File {
+        parentTask.fileLayout = object : DokkaMultiModuleFileLayout {
+            override fun targetChildOutputDirectory(parent: DokkaMultiModuleTask, child: AbstractDokkaTask): File {
                 return parent.project.file("target/output")
             }
         }
-        layout.copyChildOutputDirectory(parentTask, childTask)
+        parentTask.copyChildOutputDirectory(childTask)
 
         /* Assertions */
         val targetOutputDirectory = project.file("target/output")
diff --git a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTaskTest.kt b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTaskTest.kt
index a7c9946d..640d980b 100644
--- a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTaskTest.kt
+++ b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleTaskTest.kt
@@ -166,7 +166,7 @@ class DokkaMultiModuleTaskTest {
 
         parentTask.addChildTask(childTask)
         parentTask.fileLayout = object : DokkaMultiModuleFileLayout {
-            override fun targetChildOutputDirectory(parent: AbstractDokkaParentTask, child: AbstractDokkaTask): File {
+            override fun targetChildOutputDirectory(parent: DokkaMultiModuleTask, child: AbstractDokkaTask): File {
                 return parent.project.buildDir.resolve(child.name)
             }
         }
-- 
cgit