diff --git a/core/src/main/kotlin/model/DisplaySourceSet.kt b/core/src/main/kotlin/model/DisplaySourceSet.kt
index a39e13abb9..7b86575bff 100644
--- a/core/src/main/kotlin/model/DisplaySourceSet.kt
+++ b/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 }