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, 2 insertions, 22 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;