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, 40 insertions, 15 deletions

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 }