Simplify multi-module documentation

README.md

@@ -141,7 +141,6 @@ dokkaHtml {
     cacheRoot.set(file("default"))
     dokkaSourceSets {
         configureEach { // Or source set name, for single-platform the default source sets are `main` and `test`
-            moduleDisplayName.set("data")
 
             // Used when configuring source sets manually for declaring which source sets this one depends on
             dependsOn("otherSourceSetName")
@@ -407,7 +406,7 @@ The available configuration options are shown below:
         <skip>false</skip>
 
         <!-- Default: ${project.artifactId} -->
-        <moduleDisplayName>data</moduleDisplayName>
+        <moduleName>data</moduleName>
 
         <!-- Default: ${project.basedir}/target/dokka -->
         <outputDir>some/out/dir</outputDir>
@@ -556,7 +555,6 @@ Dokka supports the following command line arguments:
   * `-globalSrcLink` - source links added to all source sets
   * `-sourceSet` - (repeatable) - configuration for a single source set. Following this argument, you can pass other arguments:
     * `-moduleName` - (required) - module name used as a part of source set ID when declaring dependent source sets
-    * `-moduleDisplayName` - displayed module name
     * `-sourceSetName` - source set name as a part of source set ID when declaring dependent source sets
     * `-displayName` - source set name displayed in the generated documentation
     * `-src` - list of source files or directories separated by `;`

core/src/main/kotlin/DokkaException.kt

@@ -1,3 +1,3 @@
 package org.jetbrains.dokka
 
-class DokkaException(message: String) : RuntimeException(message)
+open class DokkaException(message: String) : RuntimeException(message)

core/src/main/kotlin/configuration.kt

@@ -9,6 +9,7 @@ import java.io.Serializable
 import java.net.URL
 
 object DokkaDefaults {
+    val moduleName: String = "root"
     val outputDir = File("./dokka")
     const val format: String = "html"
     val cacheRoot: File? = null
@@ -58,12 +59,21 @@ interface DokkaConfigurationBuilder<T : Any> {
 
 fun <T : Any> Iterable<DokkaConfigurationBuilder<T>>.build(): List<T> = this.map { it.build() }
 
+
 data class DokkaSourceSetID(
-    val moduleName: String,
+    /**
+     * Unique identifier of the scope that this source set is placed in.
+     * Each scope provide only unique source set names.
+     *
+     * E.g. One DokkaTask inside the Gradle plugin represents one source set scope, since there cannot be multiple
+     * source sets with the same name. However, a Gradle project will not be a proper scope, since there can be
+     * multple DokkaTasks that contain source sets with the same name (but different configuration)
+     */
+    val scopeId: String,
     val sourceSetName: String
 ) : Serializable {
     override fun toString(): String {
-        return "$moduleName/$sourceSetName"
+        return "$scopeId/$sourceSetName"
     }
 }
 
@@ -72,6 +82,7 @@ fun DokkaConfigurationImpl(json: String): DokkaConfigurationImpl = parseJson(jso
 fun DokkaConfiguration.toJsonString(): String = toJsonString(this)
 
 interface DokkaConfiguration : Serializable {
+    val moduleName: String
     val outputDir: File
     val cacheRoot: File?
     val offlineMode: Boolean
@@ -84,7 +95,6 @@ interface DokkaConfiguration : Serializable {
     interface DokkaSourceSet : Serializable {
         val sourceSetID: DokkaSourceSetID
         val displayName: String
-        val moduleDisplayName: String
         val classpath: List<File>
         val sourceRoots: Set<File>
         val dependentSourceSets: Set<DokkaSourceSetID>
@@ -114,8 +124,8 @@ interface DokkaConfiguration : Serializable {
 
     interface DokkaModuleDescription : Serializable {
         val name: String
-        val path: File
-        val docFile: File
+        val relativePathToOutputDirectory: File
+        val includes: Set<File>
     }
 
     interface PackageOptions : Serializable {

core/src/main/kotlin/defaultConfiguration.kt

@@ -5,6 +5,7 @@ import java.io.File
 import java.net.URL
 
 data class DokkaConfigurationImpl(
+    override val moduleName: String = DokkaDefaults.moduleName,
     override val outputDir: File = DokkaDefaults.outputDir,
     override val cacheRoot: File? = DokkaDefaults.cacheRoot,
     override val offlineMode: Boolean = DokkaDefaults.offlineMode,
@@ -17,7 +18,6 @@ data class DokkaConfigurationImpl(
 
 
 data class DokkaSourceSetImpl(
-    override val moduleDisplayName: String,
     override val displayName: String = DokkaDefaults.sourceSetDisplayName,
     override val sourceSetID: DokkaSourceSetID,
     override val classpath: List<File> = emptyList(),
@@ -43,8 +43,8 @@ data class DokkaSourceSetImpl(
 
 data class DokkaModuleDescriptionImpl(
     override val name: String,
-    override val path: File,
-    override val docFile: File
+    override val relativePathToOutputDirectory: File,
+    override val includes: Set<File>
 ) : DokkaConfiguration.DokkaModuleDescription
 
 data class SourceLinkDefinitionImpl(

core/src/main/kotlin/links/DRI.kt

@@ -1,7 +1,5 @@
 package org.jetbrains.dokka.links
 
-import org.jetbrains.dokka.model.ClassKind
-
 /**
  * [DRI] stands for DokkaResourceIdentifier
  */

core/src/main/kotlin/model/CompositeSourceSetID.kt

@@ -14,8 +14,8 @@ data class CompositeSourceSetID(
     }
 
     val merged = DokkaSourceSetID(
-        moduleName = children.map { it.moduleName }.reduce { acc, s -> "$acc+$s" },
-        sourceSetName = children.map { it.sourceSetName }.reduce { acc, s -> "$acc+$s" }
+        scopeId = children.joinToString(separator = "+") { it.scopeId },
+        sourceSetName = children.joinToString(separator = "+") { it.sourceSetName }
     )
 
     val all: Set<DokkaSourceSetID> = setOf(merged, *children.toTypedArray())

core/src/main/kotlin/model/Documentable.kt

@@ -111,9 +111,18 @@ data class DPackage(
     override val sourceSets: Set<DokkaSourceSet>,
     override val extra: PropertyContainer<DPackage> = PropertyContainer.empty()
 ) : Documentable(), WithScope, WithExtraProperties<DPackage> {
-    override val name = dri.packageName.orEmpty()
-    override val children: List<Documentable>
-        get() = (properties + functions + classlikes + typealiases)
+
+    val packageName: String = dri.packageName.orEmpty()
+
+    /**
+     * !!! WARNING !!!
+     * This name is not guaranteed to be a be a canonical/real package name.
+     * e.g. this will return a human readable version for root packages.
+     * Use [packageName] or `dri.packageName` instead to obtain the real packageName
+     */
+    override val name: String = if (packageName.isBlank()) "[root]" else packageName
+
+    override val children: List<Documentable> = properties + functions + classlikes + typealiases
 
     override fun withNewExtras(newExtras: PropertyContainer<DPackage>) = copy(extra = newExtras)
 }