Document DisplaySourceSet & co

core/src/main/kotlin/model/DisplaySourceSet.kt

@@ -1,24 +1,51 @@
 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
 
-
-data class DisplaySourceSet(
+/**
+ * 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.
+ *
+ * @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]
+ */
+public data class DisplaySourceSet(
  val sourceSetIDs: CompositeSourceSetID,
  val name: String,
  val platform: Platform
 ) {
- 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)
 
-fun Iterable<DokkaSourceSet>.toDisplaySourceSets(): Set<DisplaySourceSet> = map { it.toDisplaySourceSet() }.toSet()
+/**
+ * Transforms all the given [DokkaSourceSet]s into [DisplaySourceSet].
+ */
+public fun Iterable<DokkaSourceSet>.toDisplaySourceSets(): Set<DisplaySourceSet> =
+ map { it.toDisplaySourceSet() }.toSet()
 
-val Iterable<DisplaySourceSet>.sourceSetIDs: List<DokkaSourceSetID> get() = this.flatMap { it.sourceSetIDs.all }
+@InternalDokkaApi
+public val Iterable<DisplaySourceSet>.sourceSetIDs: List<DokkaSourceSetID> get() = this.flatMap { it.sourceSetIDs.all }