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

2 files changed, 11 insertions, 6 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)))
                         }
                     }
                 }