Let root package be represented as [root] to the user

19 files changed, 67 insertions, 20 deletions

diff --git a/core/src/main/kotlin/model/Documentable.kt b/core/src/main/kotlin/model/Documentable.kt
index 293b8a30..34ad6c2b 100644
--- a/core/src/main/kotlin/model/Documentable.kt
+++ b/core/src/main/kotlin/model/Documentable.kt
@@ -111,9 +111,18 @@ data class DPackage(
     override val sourceSets: Set<DokkaSourceSet> = emptySet(),
     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)
 }
diff --git a/core/src/main/kotlin/pages/PageNodes.kt b/core/src/main/kotlin/pages/PageNodes.kt
index 176c0993..a91887b4 100644
--- a/core/src/main/kotlin/pages/PageNodes.kt
+++ b/core/src/main/kotlin/pages/PageNodes.kt
@@ -92,6 +92,11 @@ class PackagePageNode(
     override val children: List<PageNode>,
     override val embeddedResources: List<String> = listOf()
 ) : PackagePage {
+
+    init {
+        require(name.isNotBlank()) { "PackagePageNode.name cannot be blank" }
+    }
+
     override fun modified(name: String, children: List<PageNode>): PackagePageNode =
         modified(name = name, content = this.content, children = children)
 
diff --git a/integration-tests/cli/src/integrationTest/kotlin/org/jetbrains/dokka/it/cli/CliIntegrationTest.kt b/integration-tests/cli/src/integrationTest/kotlin/org/jetbrains/dokka/it/cli/CliIntegrationTest.kt
index 462ab842..6510c044 100644
--- a/integration-tests/cli/src/integrationTest/kotlin/org/jetbrains/dokka/it/cli/CliIntegrationTest.kt
+++ b/integration-tests/cli/src/integrationTest/kotlin/org/jetbrains/dokka/it/cli/CliIntegrationTest.kt
@@ -85,6 +85,7 @@ class CliIntegrationTest : AbstractCliIntegrationTest() {
             assertContainsNoErrorClass(file)
             assertNoUnresolvedLinks(file)
             assertNoEmptyLinks(file)
+            assertNoEmptySpans(file)
         }
     }
 }
diff --git a/integration-tests/gradle/projects/it-basic/src/main/kotlin/RootPackageClass.kt b/integration-tests/gradle/projects/it-basic/src/main/kotlin/RootPackageClass.kt
new file mode 100644
index 00000000..8ff6c750
--- /dev/null
+++ b/integration-tests/gradle/projects/it-basic/src/main/kotlin/RootPackageClass.kt
@@ -0,0 +1,8 @@
+@file:Suppress("unused")
+
+/**
+ * A class that lives inside the root package
+ */
+class RootPackageClass {
+    val description = "I do live in the root package!"
+}
diff --git a/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/basic/PublicClass.kt b/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/basic/PublicClass.kt
index 71bc7e63..fc4b36bd 100644
--- a/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/basic/PublicClass.kt
+++ b/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/basic/PublicClass.kt
@@ -2,6 +2,11 @@
 
 package it.basic
 
+import RootPackageClass
+
+/**
+ * This class, unlike [RootPackageClass] is located in a sub-package
+ */
 class PublicClass {
     /**
      * This function is public and documented
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Android0GradleIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Android0GradleIntegrationTest.kt
index 145992fc..bfeed55e 100644
--- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Android0GradleIntegrationTest.kt
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Android0GradleIntegrationTest.kt
@@ -59,6 +59,7 @@ class Android0GradleIntegrationTest(override val versions: BuildVersions) : Abst
             assertNoUnresolvedLinks(file, knownUnresolvedDRIs)
             assertNoHrefToMissingLocalFileOrDirectory(file)
             assertNoEmptyLinks(file)
+            assertNoEmptySpans(file)
         }
 
         assertTrue(
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt
index a0a43764..1265d675 100644
--- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt
@@ -79,6 +79,7 @@ class BasicGradleIntegrationTest(override val versions: BuildVersions) : Abstrac
             assertNoHrefToMissingLocalFileOrDirectory(file)
             assertNoSuppressedMarker(file)
             assertNoEmptyLinks(file)
+            assertNoEmptySpans(file)
         }
 
         assertTrue(
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGroovyIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGroovyIntegrationTest.kt
index 5c1480f4..0e125258 100644
--- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGroovyIntegrationTest.kt
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGroovyIntegrationTest.kt
@@ -82,6 +82,7 @@ class BasicGroovyIntegrationTest(override val versions: BuildVersions) : Abstrac
             assertNoUnresolvedLinks(file)
             assertNoHrefToMissingLocalFileOrDirectory(file)
             assertNoEmptyLinks(file)
+            assertNoEmptySpans(file)
         }
     }
 
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Collector0IntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Collector0IntegrationTest.kt
index d47a0e5f..c3971eae 100644
--- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Collector0IntegrationTest.kt
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Collector0IntegrationTest.kt
@@ -52,6 +52,7 @@ class Collector0IntegrationTest(override val versions: BuildVersions) : Abstract
             assertNoUnresolvedLinks(file)
             assertNoHrefToMissingLocalFileOrDirectory(file)
             assertNoEmptyLinks(file)
+            assertNoEmptySpans(file)
         }
 
         assertTrue(
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/MultiModule0IntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/MultiModule0IntegrationTest.kt
index 6d15de26..eedc6da3 100644
--- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/MultiModule0IntegrationTest.kt
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/MultiModule0IntegrationTest.kt
@@ -57,6 +57,7 @@ class MultiModule0IntegrationTest(override val versions: BuildVersions) : Abstra
             assertNoUnresolvedLinks(file)
             assertNoHrefToMissingLocalFileOrDirectory(file)
             assertNoEmptyLinks(file)
+            assertNoEmptySpans(file)
         }
 
         val modulesFile = File(outputDir, "-modules.html")
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Multiplatform0GradleIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Multiplatform0GradleIntegrationTest.kt
index 2f716fa7..8f7ccbd3 100644
--- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Multiplatform0GradleIntegrationTest.kt
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/Multiplatform0GradleIntegrationTest.kt
@@ -39,6 +39,7 @@ class Multiplatform0GradleIntegrationTest(override val versions: BuildVersions)
             assertNoUnresolvedLinks(file)
             assertNoHrefToMissingLocalFileOrDirectory(file)
             assertNoEmptyLinks(file)
+            assertNoEmptySpans(file)
         }
     }
 }
diff --git a/integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt b/integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt
index 1a4fec44..88fdc207 100644
--- a/integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt
+++ b/integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt
@@ -52,6 +52,7 @@ class MavenIntegrationTest : AbstractIntegrationTest() {
             assertContainsNoErrorClass(file)
             assertNoUnresolvedLinks(file)
             assertNoEmptyLinks(file)
+            assertNoEmptySpans(file)
         }
     }
 
diff --git a/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt b/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt
index 04ae4a88..2a01993e 100644
--- a/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt
+++ b/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt
@@ -90,4 +90,12 @@ abstract class AbstractIntegrationTest {
             "Unexpected `§SUPPRESSED§` in file ${file.path}"
         )
     }
+
+    protected fun assertNoEmptySpans(file: File) {
+        val fileText = file.readText()
+        assertFalse(
+            fileText.contains(Regex("""<span>\s*</span>""")),
+            "Unexpected empty <span></span> in file ${file.path}"
+        )
+    }
 }
diff --git a/plugins/base/base-test-utils/src/main/kotlin/utils/TestOutputWriter.kt b/plugins/base/base-test-utils/src/main/kotlin/utils/TestOutputWriter.kt
index 00b865b4..67e62c36 100644
--- a/plugins/base/base-test-utils/src/main/kotlin/utils/TestOutputWriter.kt
+++ b/plugins/base/base-test-utils/src/main/kotlin/utils/TestOutputWriter.kt
@@ -3,6 +3,7 @@ package utils
 import org.jetbrains.dokka.base.DokkaBase
 import org.jetbrains.dokka.base.renderers.OutputWriter
 import org.jetbrains.dokka.plugability.DokkaPlugin
+import java.util.*
 
 class TestOutputWriterPlugin(failOnOverwrite: Boolean = true) : DokkaPlugin() {
     val writer = TestOutputWriter(failOnOverwrite)
@@ -19,7 +20,7 @@ class TestOutputWriterPlugin(failOnOverwrite: Boolean = true) : DokkaPlugin() {
 class TestOutputWriter(private val failOnOverwrite: Boolean = true) : OutputWriter {
     val contents: Map<String, String> get() = _contents
 
-    private val _contents = mutableMapOf<String, String>()
+    private val _contents = Collections.synchronizedMap(mutableMapOf<String, String>())
     override suspend fun write(path: String, text: String, ext: String) {
         val fullPath = "$path$ext"
         _contents.putIfAbsent(fullPath, text)?.also {
diff --git a/plugins/base/src/main/kotlin/resolvers/local/DokkaLocationProvider.kt b/plugins/base/src/main/kotlin/resolvers/local/DokkaLocationProvider.kt
index f25f85a6..096104cc 100644
--- a/plugins/base/src/main/kotlin/resolvers/local/DokkaLocationProvider.kt
+++ b/plugins/base/src/main/kotlin/resolvers/local/DokkaLocationProvider.kt
@@ -89,10 +89,7 @@ open class DokkaLocationProvider(
     private fun PageNode.parent() = pageGraphRoot.parentMap[this]
 
     private val PageNode.pathName: String
-        get() = when (this) {
-            is PackagePageNode -> if (name.isBlank()) "[root]" else name
-            else -> identifierToFilename(name)
-        }
+        get() = if (this is PackagePageNode) name else identifierToFilename(name)
 
     companion object {
         internal val reservedFilenames = setOf("index", "con", "aux", "lst", "prn", "nul", "eof", "inp", "out")
diff --git a/plugins/base/src/test/kotlin/model/PackagesTest.kt b/plugins/base/src/test/kotlin/model/PackagesTest.kt
index 188ee2c6..1adf7626 100644
--- a/plugins/base/src/test/kotlin/model/PackagesTest.kt
+++ b/plugins/base/src/test/kotlin/model/PackagesTest.kt
@@ -22,8 +22,8 @@ class PackagesTest : AbstractModelTest("/src/main/kotlin/packages/Test.kt", "pac
                 }
             }
         ) {
-            with((this / "").cast<DPackage>()) {
-                name equals ""
+            with((this / "[root]").cast<DPackage>()) {
+                packageName equals ""
                 children counts 0
             }
         }
@@ -38,7 +38,7 @@ class PackagesTest : AbstractModelTest("/src/main/kotlin/packages/Test.kt", "pac
             prependPackage = false
         ) {
             with((this / "simple").cast<DPackage>()) {
-                name equals "simple"
+                packageName equals "simple"
                 children counts 0
             }
         }
@@ -53,7 +53,7 @@ class PackagesTest : AbstractModelTest("/src/main/kotlin/packages/Test.kt", "pac
             prependPackage = false
         ) {
             with((this / "dot.name").cast<DPackage>()) {
-                name equals "dot.name"
+                packageName equals "dot.name"
                 children counts 0
             }
         }
@@ -72,11 +72,11 @@ class PackagesTest : AbstractModelTest("/src/main/kotlin/packages/Test.kt", "pac
         ) {
             children counts 2
             with((this / "dot.name").cast<DPackage>()) {
-                name equals "dot.name"
+                packageName equals "dot.name"
                 children counts 0
             }
             with((this / "simple").cast<DPackage>()) {
-                name equals "simple"
+                packageName equals "simple"
                 children counts 0
             }
         }
@@ -94,7 +94,7 @@ class PackagesTest : AbstractModelTest("/src/main/kotlin/packages/Test.kt", "pac
         ) {
             children counts 1
             with((this / "simple").cast<DPackage>()) {
-                name equals "simple"
+                packageName equals "simple"
                 children counts 0
             }
         }
@@ -111,12 +111,14 @@ class PackagesTest : AbstractModelTest("/src/main/kotlin/packages/Test.kt", "pac
             prependPackage = false
         ) {
             with((this / "simple.name").cast<DPackage>()) {
-                name equals "simple.name"
+                packageName equals "simple.name"
                 children counts 1
             }
         }
     }
 
+    // TODO NOW test displayName
+
     // todo
 //    @Test fun suppressAtPackageLevel() {
 //        verifyModel(
diff --git a/plugins/base/src/test/kotlin/translators/utils.kt b/plugins/base/src/test/kotlin/translators/utils.kt
index 71b4a28b..cbb6efa7 100644
--- a/plugins/base/src/test/kotlin/translators/utils.kt
+++ b/plugins/base/src/test/kotlin/translators/utils.kt
@@ -20,7 +20,7 @@ fun DModule.descriptionOf(className: String, functionName: String? = null): Desc
 }
 
 fun DModule.findPackage(packageName: String? = null) =
-    packageName?.let { packages.firstOrNull { pkg -> pkg.name == packageName }
+    packageName?.let { packages.firstOrNull { pkg -> pkg.packageName == packageName }
         ?: throw NoSuchElementException("No packageName with name $packageName") } ?: packages.single()
 
 fun DModule.findClasslike(packageName: String? = null, className: String? = null): DClasslike {
@@ -37,4 +37,4 @@ fun DModule.findFunction(packageName: String? = null, className: String, functio
         classlike.functions.firstOrNull { fn -> fn.name == functionName }
             ?: throw NoSuchElementException("No classlike with name $functionName")
     } ?: classlike.functions.single()
-}
\ No newline at end of file
+}
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt
index 05de8fa1..2fb00335 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt
@@ -84,7 +84,7 @@ open class JavadocPageCreator(
             leafList(setOf(m.dri),
                 ContentKind.Packages, JavadocList(
                     "Packages", "Package",
-                    m.packages.sortedBy { it.name }.map { p ->
+                    m.packages.sortedBy { it.packageName }.map { p ->
                         RowJavadocListEntry(
                             LinkJavadocListEntry(p.name, setOf(p.dri), JavadocContentKind.PackageSummary, sourceSets),
                             p.brief()
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt
index 3875c307..2f26ea79 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt
@@ -74,6 +74,10 @@ class JavadocPackagePageNode(
     NavigableJavadocNode,
     PackagePage {
 
+    init {
+        require(name.isNotBlank()) { "Empty name is not supported " }
+    }
+
     override fun getAllNavigables(): List<NavigableJavadocNode> =
         children.filterIsInstance<NavigableJavadocNode>().flatMap {
             if (it is WithNavigable) it.getAllNavigables()
@@ -568,4 +572,4 @@ private fun Documentable.kind(): String? =
         is DObject -> "object"
         is DInterface -> "interface"
         else -> null
-    }
\ No newline at end of file
+    }