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

19 files changed, 130 insertions, 205 deletions

diff --git a/core/api/core.api b/core/api/core.api
index 9530899d..6da499ee 100644
--- a/core/api/core.api
+++ b/core/api/core.api
@@ -863,10 +863,6 @@ public final class org/jetbrains/dokka/model/CompositeSourceSetID {
 	public fun toString ()Ljava/lang/String;
 }
 
-public final class org/jetbrains/dokka/model/CompositeSourceSetIDKt {
-	public static final fun plus (Lorg/jetbrains/dokka/DokkaSourceSetID;Lorg/jetbrains/dokka/DokkaSourceSetID;)Lorg/jetbrains/dokka/model/CompositeSourceSetID;
-}
-
 public final class org/jetbrains/dokka/model/Contravariance : org/jetbrains/dokka/model/Variance {
 	public fun <init> (Lorg/jetbrains/dokka/model/Bound;)V
 	public final fun component1 ()Lorg/jetbrains/dokka/model/Bound;
@@ -1400,40 +1396,24 @@ public final class org/jetbrains/dokka/model/DefinitelyNonNullable : org/jetbrai
 	public fun toString ()Ljava/lang/String;
 }
 
-public final class org/jetbrains/dokka/model/DisplaySourceSet : org/jetbrains/dokka/utilities/SelfRepresentingSingletonSet {
+public final class org/jetbrains/dokka/model/DisplaySourceSet {
 	public fun <init> (Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)V
 	public fun <init> (Lorg/jetbrains/dokka/model/CompositeSourceSetID;Ljava/lang/String;Lorg/jetbrains/dokka/Platform;)V
-	public synthetic fun add (Ljava/lang/Object;)Z
-	public fun add (Lorg/jetbrains/dokka/model/DisplaySourceSet;)Z
-	public fun addAll (Ljava/util/Collection;)Z
-	public fun clear ()V
 	public final fun component1 ()Lorg/jetbrains/dokka/model/CompositeSourceSetID;
 	public final fun component2 ()Ljava/lang/String;
 	public final fun component3 ()Lorg/jetbrains/dokka/Platform;
-	public final fun contains (Ljava/lang/Object;)Z
-	public fun contains (Lorg/jetbrains/dokka/model/DisplaySourceSet;)Z
-	public synthetic fun contains (Lorg/jetbrains/dokka/utilities/SelfRepresentingSingletonSet;)Z
-	public fun containsAll (Ljava/util/Collection;)Z
 	public final fun copy (Lorg/jetbrains/dokka/model/CompositeSourceSetID;Ljava/lang/String;Lorg/jetbrains/dokka/Platform;)Lorg/jetbrains/dokka/model/DisplaySourceSet;
 	public static synthetic fun copy$default (Lorg/jetbrains/dokka/model/DisplaySourceSet;Lorg/jetbrains/dokka/model/CompositeSourceSetID;Ljava/lang/String;Lorg/jetbrains/dokka/Platform;ILjava/lang/Object;)Lorg/jetbrains/dokka/model/DisplaySourceSet;
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getName ()Ljava/lang/String;
 	public final fun getPlatform ()Lorg/jetbrains/dokka/Platform;
-	public fun getSize ()I
 	public final fun getSourceSetIDs ()Lorg/jetbrains/dokka/model/CompositeSourceSetID;
 	public fun hashCode ()I
-	public fun isEmpty ()Z
-	public fun iterator ()Ljava/util/Iterator;
-	public fun remove (Ljava/lang/Object;)Z
-	public fun removeAll (Ljava/util/Collection;)Z
-	public fun retainAll (Ljava/util/Collection;)Z
-	public final fun size ()I
-	public fun toArray ()[Ljava/lang/Object;
-	public fun toArray ([Ljava/lang/Object;)[Ljava/lang/Object;
 	public fun toString ()Ljava/lang/String;
 }
 
 public final class org/jetbrains/dokka/model/DisplaySourceSetKt {
+	public static final fun computeSourceSetIds (Ljava/lang/Iterable;)Ljava/util/Set;
 	public static final fun getSourceSetIDs (Ljava/lang/Iterable;)Ljava/util/List;
 	public static final fun toDisplaySourceSet (Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Lorg/jetbrains/dokka/model/DisplaySourceSet;
 	public static final fun toDisplaySourceSets (Ljava/lang/Iterable;)Ljava/util/Set;
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
 
diff --git a/core/src/test/kotlin/model/CompositeSourceSetIDTest.kt b/core/src/test/kotlin/model/CompositeSourceSetIDTest.kt
index 472581e7..aa5a801d 100644
--- a/core/src/test/kotlin/model/CompositeSourceSetIDTest.kt
+++ b/core/src/test/kotlin/model/CompositeSourceSetIDTest.kt
@@ -2,7 +2,6 @@ package model
 
 import org.jetbrains.dokka.DokkaSourceSetID
 import org.jetbrains.dokka.model.CompositeSourceSetID
-import org.jetbrains.dokka.model.plus
 import kotlin.test.*
 
 class CompositeSourceSetIDTest {
@@ -65,4 +64,9 @@ class CompositeSourceSetIDTest {
             "Expected all three source sets being merged in order"
         )
     }
+
+    operator fun DokkaSourceSetID.plus(other: DokkaSourceSetID): CompositeSourceSetID {
+        return CompositeSourceSetID(listOf(this, other))
+    }
+
 }
diff --git a/core/src/test/kotlin/model/DisplaySourceSetTest.kt b/core/src/test/kotlin/model/DisplaySourceSetTest.kt
index adabdbdb..04ad07d6 100644
--- a/core/src/test/kotlin/model/DisplaySourceSetTest.kt
+++ b/core/src/test/kotlin/model/DisplaySourceSetTest.kt
@@ -2,9 +2,7 @@ package model
 
 import org.jetbrains.dokka.DokkaSourceSetID
 import org.jetbrains.dokka.Platform
-import org.jetbrains.dokka.model.CompositeSourceSetID
-import org.jetbrains.dokka.model.DisplaySourceSet
-import org.jetbrains.dokka.model.sourceSetIDs
+import org.jetbrains.dokka.model.*
 import kotlin.test.Test
 import kotlin.test.assertFalse
 import kotlin.test.assertTrue
@@ -44,17 +42,17 @@ class DisplaySourceSetTest {
         )
 
         assertFalse(
-            DokkaSourceSetID("m3", "s3") in listOf(contentSourceSet).sourceSetIDs,
+            DokkaSourceSetID("m3", "s3") in listOf(contentSourceSet).computeSourceSetIds(),
             "Expected source set id not being contained in content source set"
         )
 
         assertTrue(
-            DokkaSourceSetID("m1", "s1") in listOf(contentSourceSet).sourceSetIDs,
+            DokkaSourceSetID("m1", "s1") in listOf(contentSourceSet).computeSourceSetIds(),
             "Expected source set id being contained in content source set"
         )
 
         assertTrue(
-            DokkaSourceSetID("m1+m2", "s1+s2") in listOf(contentSourceSet).sourceSetIDs,
+            DokkaSourceSetID("m1+m2", "s1+s2") in listOf(contentSourceSet).computeSourceSetIds(),
             "Expected merged source set being contained in content source set"
         )
     }
diff --git a/core/src/test/kotlin/utilities/SelfRepresentingSingletonSetTest.kt b/core/src/test/kotlin/utilities/SelfRepresentingSingletonSetTest.kt
deleted file mode 100644
index bef43565..00000000
--- a/core/src/test/kotlin/utilities/SelfRepresentingSingletonSetTest.kt
+++ /dev/null
@@ -1,60 +0,0 @@
-package utilities
-
-import org.jetbrains.dokka.utilities.SelfRepresentingSingletonSet
-import kotlin.test.Test
-import kotlin.test.assertEquals
-import kotlin.test.assertFalse
-import kotlin.test.assertTrue
-
-class SelfRepresentingSingletonSetTest {
-
-    data class TestModel(val index: Int = 0) : SelfRepresentingSingletonSet<TestModel>
-
-    @Test
-    fun size() {
-        assertEquals(1, TestModel().size)
-    }
-
-    @Test
-    fun contains() {
-        val m0 = TestModel(0)
-        val m1 = TestModel(1)
-
-        assertFalse(m1 in m0)
-        assertFalse(m0 in m1)
-        assertTrue(m0 in m0)
-        assertTrue(m1 in m1)
-        assertTrue(TestModel(0) in m0)
-    }
-
-    @Test
-    fun `containsAll is compliant to setOf`() {
-        val setOf = setOf(TestModel())
-        val testModel = TestModel()
-
-        assertEquals(
-            setOf.containsAll(emptyList()), testModel.containsAll(emptyList())
-        )
-
-        assertEquals(
-            setOf.containsAll(listOf(TestModel())), testModel.containsAll(listOf(TestModel()))
-        )
-
-        assertEquals(
-            setOf.containsAll(listOf(TestModel(0), TestModel(1))),
-            testModel.containsAll(listOf(TestModel(0), TestModel(1)))
-        )
-    }
-
-    @Test
-    fun isEmpty() {
-        assertFalse(TestModel().isEmpty())
-    }
-
-    @Test
-    fun iterator() {
-        assertEquals(
-            listOf(TestModel()), TestModel(0).iterator().asSequence().toList()
-        )
-    }
-}
diff --git a/integration-tests/gradle/README.md b/integration-tests/gradle/README.md
index 45828092..706cfb61 100644
--- a/integration-tests/gradle/README.md
+++ b/integration-tests/gradle/README.md
@@ -5,3 +5,17 @@ build.gradle.kts file -> "import gradle project".
 
 Before importing: Make sure that you have dokka installed
 locally (`./gradlew publishToMavenLocal`).
+
+### To update git submodules 
+
+Integration tests have fixed git revision number, with the diff patch applied from the corresponding file (e.g. [`coroutines.diff`](projects/coroutines/coroutines.diff)).
+
+In order to update:
+
+* Checkout the project with the requered revision
+    - It's some state of the `master`
+* Manually write the diff (or apply the existing one and tweak) to have the project buildable against locally published Dokka of version `for-integration-tests-SNAPSHOT`
+* `git diff > $pathToProjectInDokka/project.diff`
+* Go to `$pathToProjectInDokka`, `git fetch && git checkout $revisionNumber`
+    - Prior to that, ensure that you have your git submodules initialized
+* Ensure that the corresponding `GradleIntegrationTest` passes locally and push
diff --git a/integration-tests/gradle/projects/coroutines/coroutines.diff b/integration-tests/gradle/projects/coroutines/coroutines.diff
index 4d95307c..d2216f1b 100644
--- a/integration-tests/gradle/projects/coroutines/coroutines.diff
+++ b/integration-tests/gradle/projects/coroutines/coroutines.diff
@@ -1,17 +1,27 @@
 diff --git a/build.gradle b/build.gradle
-index 934d4c220..38321990e 100644
+index e7d405e12..0ca2169fe 100644
 --- a/build.gradle
 +++ b/build.gradle
-@@ -131,6 +131,7 @@ allprojects {
+@@ -107,6 +107,9 @@ allprojects {
+             mavenLocal()
+         }
+     }
++    repositories {
++        mavenLocal()
++    }
+
+     ext.unpublished = unpublished
+
+@@ -142,6 +145,7 @@ allprojects {
          google()
          mavenCentral()
          CommunityProjectsBuild.addDevRepositoryIfEnabled(delegate, project)
 +        mavenLocal()
      }
  }
- 
+
 diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts
-index 785d13fdb..7fb19f467 100644
+index ae54ad0f6..4655940a9 100644
 --- a/buildSrc/build.gradle.kts
 +++ b/buildSrc/build.gradle.kts
 @@ -25,6 +25,7 @@ repositories {
@@ -20,8 +30,8 @@ index 785d13fdb..7fb19f467 100644
      }
 +    mavenLocal()
  }
- 
- kotlinDslPluginOptions {
+
+ val gradleProperties = Properties().apply {
 diff --git a/buildSrc/settings.gradle.kts b/buildSrc/settings.gradle.kts
 index c2e859f65..43dc4f749 100644
 --- a/buildSrc/settings.gradle.kts
@@ -34,14 +44,14 @@ index c2e859f65..43dc4f749 100644
      }
  }
 diff --git a/gradle.properties b/gradle.properties
-index db7cf099b..9c13c46fd 100644
+index 3d9431be0..b60114bc2 100644
 --- a/gradle.properties
 +++ b/gradle.properties
-@@ -14,7 +14,7 @@ atomicfu_version=0.18.5
- knit_version=0.4.0
+@@ -14,7 +14,7 @@ atomicfu_version=0.21.0
+ knit_version=0.5.0-Beta
  html_version=0.7.2
- lincheck_version=2.14.1
--dokka_version=1.7.20
+ lincheck_version=2.18.1
+-dokka_version=1.8.10
 +dokka_version=for-integration-tests-SNAPSHOT
  byte_buddy_version=1.10.9
  reactor_version=3.4.1
diff --git a/integration-tests/gradle/projects/coroutines/kotlinx-coroutines b/integration-tests/gradle/projects/coroutines/kotlinx-coroutines
-Subproject b74e039196711512764add6f94af92f99d09d3a
+Subproject b78bbf518bd8e90e9ed2133ebdacc36441210cd
diff --git a/integration-tests/gradle/projects/serialization/kotlinx-serialization b/integration-tests/gradle/projects/serialization/kotlinx-serialization
-Subproject daa95c79ffadc0eedbbb4a481a00556b78212e4
+Subproject ed1b05707ec27f8864c8b42235b299bdb5e0015
diff --git a/integration-tests/gradle/projects/serialization/serialization.diff b/integration-tests/gradle/projects/serialization/serialization.diff
index 04783fb6..aac4a0c6 100644
--- a/integration-tests/gradle/projects/serialization/serialization.diff
+++ b/integration-tests/gradle/projects/serialization/serialization.diff
@@ -1,62 +1,13 @@
-diff --git a/build.gradle b/build.gradle
-index 0d21932a..4c5a9c7f 100644
---- a/build.gradle
-+++ b/build.gradle
-@@ -63,7 +63,6 @@ buildscript {
-     dependencies {
-         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
-         classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"
--        classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version"
-         classpath "org.jetbrains.kotlinx:kover:$kover_version"
-         classpath "org.jetbrains.kotlinx:binary-compatibility-validator:$validator_version"
-         classpath "org.jetbrains.kotlinx:kotlinx-knit:$knit_version"
-@@ -77,6 +76,10 @@ buildscript {
-     }
- }
-
-+plugins {
-+    id("org.jetbrains.dokka")
-+}
-+
- // To make it visible for compiler-version.gradle
- ext.compilerVersion = org.jetbrains.kotlin.config.KotlinCompilerVersion.VERSION
- ext.nativeDebugBuild = org.jetbrains.kotlin.gradle.plugin.mpp.NativeBuildType.DEBUG
-@@ -97,7 +100,6 @@ knit {
- // Build API docs for all modules with dokka before running Knit
- knitPrepare.dependsOn "dokka"
-
--apply plugin: 'org.jetbrains.dokka'
- dependencies {
-     dokkaPlugin("org.jetbrains.kotlinx:dokka-pathsaver-plugin:$knit_version")
- }
-@@ -188,6 +190,7 @@ subprojects {
- apply from: rootProject.file('gradle/compiler-version.gradle')
- apply from: rootProject.file("gradle/dokka.gradle")
- apply from: rootProject.file("gradle/benchmark-parsing.gradle")
-+apply from: "../template.root.gradle.kts"
-
- tasks.named("dokkaHtmlMultiModule") {
-     pluginsMapConfiguration.set(["org.jetbrains.dokka.base.DokkaBase": """{ "templatesDir": "${projectDir.toString().replace('\\', '/')}/dokka-templates" }"""])
 diff --git a/gradle.properties b/gradle.properties
-index c4888992..d845be67 100644
+index 5ef66cd9..51a90924 100644
 --- a/gradle.properties
 +++ b/gradle.properties
-@@ -13,7 +13,7 @@ kotlin.version.snapshot=1.8.255-SNAPSHOT
+@@ -13,7 +13,7 @@ kotlin.version.snapshot=1.9.255-SNAPSHOT
 
  junit_version=4.12
  jackson_version=2.10.0.pr1
--dokka_version=1.7.0
+-dokka_version=1.8.10
 +dokka_version=for-integration-tests-SNAPSHOT
  native.deploy=
- validator_version=0.10.1
- knit_version=0.3.0
-diff --git a/settings.gradle b/settings.gradle
-index 01d4ea62..aa1800d6 100644
---- a/settings.gradle
-+++ b/settings.gradle
-@@ -36,3 +36,5 @@ project(':benchmark').projectDir = file('./benchmark')
-
- include ':guide'
- project(':guide').projectDir = file('./guide')
-+
-+apply from: "../template.settings.gradle.kts"
+ validator_version=0.13.2
+ knit_version=0.5.0-Beta
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/SerializationGradleIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/SerializationGradleIntegrationTest.kt
index 126899b2..ff929391 100644
--- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/SerializationGradleIntegrationTest.kt
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/SerializationGradleIntegrationTest.kt
@@ -15,8 +15,8 @@ class SerializationGradleIntegrationTest(override val versions: BuildVersions) :
         @get:JvmStatic
         @get:Parameterized.Parameters(name = "{0}")
         val versions = BuildVersions.permutations(
-            gradleVersions = listOf("7.4.2"),
-            kotlinVersions = listOf("1.7.10")
+            gradleVersions = listOf("7.6.1"),
+            kotlinVersions = listOf("1.9.0")
         )
     }
 
diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api
index b711700e..fb55fe94 100644
--- a/plugins/base/api/base.api
+++ b/plugins/base/api/base.api
@@ -196,6 +196,7 @@ public abstract class org/jetbrains/dokka/base/renderers/DefaultRenderer : org/j
 	public fun buildCodeBlock (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentCodeBlock;Lorg/jetbrains/dokka/pages/ContentPage;)V
 	public fun buildCodeInline (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentCodeInline;Lorg/jetbrains/dokka/pages/ContentPage;)V
 	public fun buildContentNode (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentNode;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V
+	public final fun buildContentNode (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentNode;Lorg/jetbrains/dokka/pages/ContentPage;Lorg/jetbrains/dokka/model/DisplaySourceSet;)V
 	public static synthetic fun buildContentNode$default (Lorg/jetbrains/dokka/base/renderers/DefaultRenderer;Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentNode;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;ILjava/lang/Object;)V
 	public fun buildDRILink (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentDRILink;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V
 	public fun buildDivergent (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentDivergentGroup;Lorg/jetbrains/dokka/pages/ContentPage;)V
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 {
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt
index 616583c8..f108b46a 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPageCreator.kt
@@ -206,7 +206,7 @@ open class JavadocPageCreator(context: DokkaContext) {
         }
 
     fun List<ContentNode>.nodeForJvm(jvm: DokkaSourceSet): ContentNode =
-        firstOrNull { jvm.sourceSetID in it.sourceSets.sourceSetIDs }
+        firstOrNull { jvm.sourceSetID in it.sourceSets.computeSourceSetIds() }
             ?: throw IllegalStateException("No source set found for ${jvm.sourceSetID} ")
 
     private fun Documentable.brief(sourceSet: DokkaSourceSet? = highestJvmSourceSet): List<ContentNode> =