Refactor and document DisplaySourceSet, deprecate SelfRepresentingSingletonSet (#3105)

* Deprecate internal API SelfRepresentingSingletonSet for removal as being harmful and unimplement it in DisplaySourceSet
* Provide no automatic migration for DisplaySourceSet, as there are no mechanisms for that. Manual migration is the replacement of 'dss' to `setOf(dss)` where applicable
* Introduce a convenience-member DefaultRenderer.buildContentNode to avoid wrapping DSS into set manually
* Document DisplaySourceSet
* Replace Iterable<DisplaySourceSet>.sourceSetIDs with more straightforward Iterable<DisplaySourceSet>.computeSourceSetIds(), refactor all the usages, save some allocations
* Start caching CompositeSourceSetID properties to avoid excessive allocations
* Update integration tests on the latest revision with Knit version where the workaround is applied

Fixes #2897

1 files changed, 16 insertions, 16 deletions

diff --git a/core/src/main/kotlin/model/CompositeSourceSetID.kt b/core/src/main/kotlin/model/CompositeSourceSetID.kt
index 3eaf6407..5b6ecb2a 100644
--- a/core/src/main/kotlin/model/CompositeSourceSetID.kt
+++ b/core/src/main/kotlin/model/CompositeSourceSetID.kt
@@ -3,26 +3,30 @@ package org.jetbrains.dokka.model
 import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.DokkaSourceSetID
 
-data class CompositeSourceSetID(
+/**
+ * A unique composite key of multiple [DokkaSourceSetID] that identifies [DisplaySourceSet].
+ * Consists of multiple (non-zero) [DokkaSourceSetID] that the corresponding [DisplaySourceSet] was built from.
+ *
+ * Should not be constructed or copied outside of [DisplaySourceSet] instantiation.
+ */
+public data class CompositeSourceSetID(
     private val children: Set<DokkaSourceSetID>
 ) {
-    constructor(sourceSetIDs: Iterable<DokkaSourceSetID>) : this(sourceSetIDs.toSet())
-    constructor(sourceSetId: DokkaSourceSetID) : this(setOf(sourceSetId))
+    public constructor(sourceSetIDs: Iterable<DokkaSourceSetID>) : this(sourceSetIDs.toSet())
+    public constructor(sourceSetId: DokkaSourceSetID) : this(setOf(sourceSetId))
 
     init {
         require(children.isNotEmpty()) { "Expected at least one source set id" }
     }
 
-    val merged: DokkaSourceSetID
-        get() = children.sortedBy { it.scopeId + it.sourceSetName }.let { sortedChildren ->
-            DokkaSourceSetID(
-                scopeId = sortedChildren.joinToString(separator = "+") { it.scopeId },
-                sourceSetName = sortedChildren.joinToString(separator = "+") { it.sourceSetName }
-            )
-        }
+    public val merged: DokkaSourceSetID = children.sortedBy { it.scopeId + it.sourceSetName }.let { sortedChildren ->
+        DokkaSourceSetID(
+            scopeId = sortedChildren.joinToString(separator = "+") { it.scopeId },
+            sourceSetName = sortedChildren.joinToString(separator = "+") { it.sourceSetName }
+        )
+    }
 
-    val all: Set<DokkaSourceSetID>
-        get() = setOf(merged, *children.toTypedArray())
+    public val all: Set<DokkaSourceSetID> = setOf(merged, *children.toTypedArray())
 
     operator fun contains(sourceSetId: DokkaSourceSetID): Boolean {
         return sourceSetId in all
@@ -36,7 +40,3 @@ data class CompositeSourceSetID(
         return copy(children = children + other)
     }
 }
-
-operator fun DokkaSourceSetID.plus(other: DokkaSourceSetID): CompositeSourceSetID {
-    return CompositeSourceSetID(listOf(this, other))
-}