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

4 files changed, 17 insertions, 17 deletions

diff --git a/plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt b/plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt
index e0f80324..88dc92f0 100644
--- a/plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt
+++ b/plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt
@@ -97,8 +97,13 @@ abstract class DefaultRenderer<T>(
         builder: T,
         pageContext: ContentPage,
         sourceSetRestriction: Set<DisplaySourceSet>? = null
-    ) =
-        builder.buildContentNode(this, pageContext, sourceSetRestriction)
+    ) = builder.buildContentNode(this, pageContext, sourceSetRestriction)
+
+    fun T.buildContentNode(
+        node: ContentNode,
+        pageContext: ContentPage,
+        sourceSetRestriction: DisplaySourceSet
+    ) = buildContentNode(node, pageContext, setOf(sourceSetRestriction))
 
     open fun T.buildContentNode(
         node: ContentNode,
diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
index 6885efc5..074e667e 100644
--- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
@@ -309,7 +309,7 @@ open class HtmlRenderer(
         return nodes.toList().map { (sourceSet, elements) ->
             val htmlContent = createHTML(prettyPrint = false).prepareForTemplates().div {
                 elements.forEach {
-                    buildContentNode(it, pageContext, sourceSet.toSet())
+                    buildContentNode(it, pageContext, sourceSet)
                 }
             }.stripDiv()
             sourceSet to createHTML(prettyPrint = false).prepareForTemplates()
@@ -356,7 +356,7 @@ open class HtmlRenderer(
                 distinct.onEachIndexed{ index, (_, distinctInstances) ->
                     distinctInstances.firstOrNull()?.before?.let { contentOfSourceSet.add(it) }
                     contentOfSourceSet.addAll(distinctInstances.map { it.divergent })
-                    (distinctInstances.firstOrNull()?.after ?: if (index != distinct.size - 1) ContentBreakLine(it.key) else null)
+                    (distinctInstances.firstOrNull()?.after ?: if (index != distinct.size - 1) ContentBreakLine(setOf(it.key)) else null)
                         ?.let { contentOfSourceSet.add(it) }
 
                     // content kind main is important for declarations list to avoid double line breaks
@@ -364,9 +364,9 @@ open class HtmlRenderer(
                         if (isPageWithOverloadedMembers) {
                             // add some spacing and distinction between function/property overloads.
                             // not ideal, but there's no other place to modify overloads page atm
-                            contentOfSourceSet.add(ContentBreakLine(it.key, style = setOf(HorizontalBreakLineStyle)))
+                            contentOfSourceSet.add(ContentBreakLine(setOf(it.key), style = setOf(HorizontalBreakLineStyle)))
                         } else {
-                            contentOfSourceSet.add(ContentBreakLine(it.key))
+                            contentOfSourceSet.add(ContentBreakLine(setOf(it.key)))
                         }
                     }
                 }
diff --git a/plugins/base/src/main/kotlin/resolvers/local/DokkaLocationProvider.kt b/plugins/base/src/main/kotlin/resolvers/local/DokkaLocationProvider.kt
index 4934e8f4..1c7ffe14 100644
--- a/plugins/base/src/main/kotlin/resolvers/local/DokkaLocationProvider.kt
+++ b/plugins/base/src/main/kotlin/resolvers/local/DokkaLocationProvider.kt
@@ -4,10 +4,7 @@ import org.jetbrains.dokka.base.renderers.sourceSets
 import org.jetbrains.dokka.base.resolvers.anchors.SymbolAnchorHint
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.links.PointingToDeclaration
-import org.jetbrains.dokka.model.DisplaySourceSet
-import org.jetbrains.dokka.model.sourceSetIDs
-import org.jetbrains.dokka.model.toDisplaySourceSet
-import org.jetbrains.dokka.model.withDescendants
+import org.jetbrains.dokka.model.*
 import org.jetbrains.dokka.pages.*
 import org.jetbrains.dokka.plugability.DokkaContext
 import java.util.*
@@ -91,12 +88,12 @@ open class DokkaLocationProvider(
         val (dri, originalSourceSet) = driWithSourceSets
         val allSourceSets: List<Set<DisplaySourceSet>> =
             listOf(originalSourceSet) + originalSourceSet.let { oss ->
-                dokkaContext.configuration.sourceSets.filter { it.sourceSetID in oss.sourceSetIDs }
+                val ossIds = oss.computeSourceSetIds()
+                dokkaContext.configuration.sourceSets.filter { it.sourceSetID in ossIds }
                     .flatMap { it.dependentSourceSets }
                     .mapNotNull { ssid ->
                         dokkaContext.configuration.sourceSets.find { it.sourceSetID == ssid }?.toDisplaySourceSet()
                     }.map {
-                        // be careful `data DisplaySourceSet: Set<DisplaySourceSet>` but `setOf(someDisplaySourceSet) != someDisplaySourceSet`
                         setOf(it)
                     }
             }
diff --git a/plugins/base/src/main/kotlin/transformers/pages/sourcelinks/SourceLinksTransformer.kt b/plugins/base/src/main/kotlin/transformers/pages/sourcelinks/SourceLinksTransformer.kt
index f2c3d3f0..08439ff8 100644
--- a/plugins/base/src/main/kotlin/transformers/pages/sourcelinks/SourceLinksTransformer.kt
+++ b/plugins/base/src/main/kotlin/transformers/pages/sourcelinks/SourceLinksTransformer.kt
@@ -5,10 +5,7 @@ import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
 import org.jetbrains.dokka.base.DokkaBase
 import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder
 import org.jetbrains.dokka.links.DRI
-import org.jetbrains.dokka.model.Documentable
-import org.jetbrains.dokka.model.DocumentableSource
-import org.jetbrains.dokka.model.WithSources
-import org.jetbrains.dokka.model.sourceSetIDs
+import org.jetbrains.dokka.model.*
 import org.jetbrains.dokka.pages.*
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.plugin
@@ -87,9 +84,10 @@ class SourceLinksTransformer(val context: DokkaContext) : PageTransformer {
         contentNode: ContentNode, sources: Map<DRI, List<Pair<DokkaSourceSet, String>>>
     ): ContentNode =
         contentNode.signatureGroupOrNull()?.let { sg ->
+            val sgIds = sg.sourceSets.computeSourceSetIds()
             sources[sg.dci.dri.singleOrNull()]?.let { sourceLinks ->
                 sourceLinks
-                    .filter { it.first.sourceSetID in sg.sourceSets.sourceSetIDs }
+                    .filter { it.first.sourceSetID in sgIds }
                     .takeIf { it.isNotEmpty() }
                     ?.let { filteredSourcesLinks ->
                         sg.copy(children = sg.children + filteredSourcesLinks.map {