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 +++++++++++++++++-----
 1 file changed, 28 insertions(+), 8 deletions(-)

(limited to 'runners/gradle-plugin/src/main')

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()) {
-- 
cgit