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

3 files changed, 58 insertions, 31 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))
-}
diff --git a/core/src/main/kotlin/model/DisplaySourceSet.kt b/core/src/main/kotlin/model/DisplaySourceSet.kt
index 5ea1ba3d..e2818a70 100644
--- a/core/src/main/kotlin/model/DisplaySourceSet.kt
+++ b/core/src/main/kotlin/model/DisplaySourceSet.kt
@@ -1,32 +1,57 @@
 package org.jetbrains.dokka.model
 
+import org.jetbrains.dokka.*
 import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
-import org.jetbrains.dokka.DokkaSourceSetID
-import org.jetbrains.dokka.Platform
-import org.jetbrains.dokka.utilities.SelfRepresentingSingletonSet
 
 /**
- * TODO: fix the example (asymmetric equivalence relation with [Set]):
- * ```
- * val ds = DokkaSourceSetImpl(sourceSetID = DokkaSourceSetID("", "")).toDisplaySourceSet()
- * println(setOf(ds) == ds) // true
- * println(ds == setOf(ds)) // false
- * ```
+ * Represents a final user-visible source set in the documentable model that is
+ * used to specify under which source sets/targets current signatures are available,
+ * can be used to filter in and out all available signatures under the specified source set,
+ * and, depending on the format, are rendered as "platform" selectors.
+ *
+ * E.g. HTML format renders display source sets as "bubbles" that later are used for filtering
+ * and informational purposes.
+ *
+ * [DisplaySourceSet]s typically have a one-to-one correspondence to the build system source sets,
+ * are created by the base plugin from [DokkaSourceSet] and never tweaked manually.
+ * [DisplaySourceSet] is uniquely identified by the corresponding [CompositeSourceSetID].
+ *
+ * @property sourceSetIDs unique stable id of the display source set.
+ *  It is composite by definition, as it uniquely defines the source set and all nested source sets.
+ *  Apart from names, it also contains a substitute to a full source set path in order to differentiate
+ *  source sets with the same name in a stable manner.
+ * @property name corresponds to the name of the original [DokkaSourceSet]
+ * @property platform the platform of the source set. If the source set is a mix of multiple source sets
+ *  that correspond to multiple KMP platforms, then it is [Platform.common]
  */
-data class DisplaySourceSet(
+public data class DisplaySourceSet(
     val sourceSetIDs: CompositeSourceSetID,
     val name: String,
     val platform: Platform
-) : SelfRepresentingSingletonSet<DisplaySourceSet> {
-    constructor(sourceSet: DokkaSourceSet) : this(
+) {
+    public constructor(sourceSet: DokkaSourceSet) : this(
         sourceSetIDs = CompositeSourceSetID(sourceSet.sourceSetID),
         name = sourceSet.displayName,
         platform = sourceSet.analysisPlatform
     )
 }
 
-fun DokkaSourceSet.toDisplaySourceSet(): DisplaySourceSet = DisplaySourceSet(this)
+/**
+ * Transforms the current [DokkaSourceSet] into [DisplaySourceSet],
+ * matching the corresponding subset of its properties to [DisplaySourceSet] properties.
+ */
+public fun DokkaSourceSet.toDisplaySourceSet(): DisplaySourceSet = DisplaySourceSet(this)
+
+/**
+ * Transforms all the given [DokkaSourceSet]s into [DisplaySourceSet]s.
+ */
+public fun Iterable<DokkaSourceSet>.toDisplaySourceSets(): Set<DisplaySourceSet> =
+    map { it.toDisplaySourceSet() }.toSet()
 
-fun Iterable<DokkaSourceSet>.toDisplaySourceSets(): Set<DisplaySourceSet> = map { it.toDisplaySourceSet() }.toSet()
+@InternalDokkaApi
+@Deprecated("Use computeSourceSetIds() and cache its results instead", replaceWith = ReplaceWith("computeSourceSetIds()"))
+public val Iterable<DisplaySourceSet>.sourceSetIDs: List<DokkaSourceSetID> get() = this.flatMap { it.sourceSetIDs.all }
 
-val Iterable<DisplaySourceSet>.sourceSetIDs: List<DokkaSourceSetID> get() = this.flatMap { it.sourceSetIDs.all }
+@InternalDokkaApi
+public fun Iterable<DisplaySourceSet>.computeSourceSetIds(): Set<DokkaSourceSetID> =
+    fold(hashSetOf()) { acc, set -> acc.addAll(set.sourceSetIDs.all); acc }
diff --git a/core/src/main/kotlin/utilities/SelfRepresentingSingletonSet.kt b/core/src/main/kotlin/utilities/SelfRepresentingSingletonSet.kt
index e1b42388..95cc9eb9 100644
--- a/core/src/main/kotlin/utilities/SelfRepresentingSingletonSet.kt
+++ b/core/src/main/kotlin/utilities/SelfRepresentingSingletonSet.kt
@@ -3,6 +3,8 @@ package org.jetbrains.dokka.utilities
 import org.jetbrains.dokka.InternalDokkaApi
 
 @InternalDokkaApi
+@Suppress("DEPRECATION_ERROR")
+@Deprecated(message = "SelfRepresentingSingletonSet is an incorrect set implementation that breaks set invariants", level = DeprecationLevel.ERROR)
 interface SelfRepresentingSingletonSet<T : SelfRepresentingSingletonSet<T>> : Set<T> {
     override val size: Int get() = 1