4 files changed, 34 insertions, 0 deletions
diff --git a/core/api/core.api b/core/api/core.api
index d17c8cb4..ddd77a5c 100644
--- a/core/api/core.api
+++ b/core/api/core.api
@@ -367,6 +367,9 @@ public final class org/jetbrains/dokka/GlobalDokkaConfiguration {
 	public fun toString ()Ljava/lang/String;
 }
 
+public abstract interface annotation class org/jetbrains/dokka/InternalDokkaApi : java/lang/annotation/Annotation {
+}
+
 public final class org/jetbrains/dokka/PackageOptionsImpl : org/jetbrains/dokka/DokkaConfiguration$PackageOptions {
 	public fun <init> (Ljava/lang/String;ZLjava/lang/Boolean;ZZLjava/util/Set;)V
 	public final fun component1 ()Ljava/lang/String;
diff --git a/core/build.gradle.kts b/core/build.gradle.kts
index a51e3a62..49b022ef 100644
--- a/core/build.gradle.kts
+++ b/core/build.gradle.kts
@@ -1,4 +1,5 @@
 import org.jetbrains.dokkaVersion
+import org.jetbrains.kotlin.gradle.tasks.*
 import org.jetbrains.registerDokkaArtifactPublication
 
 plugins {
@@ -39,6 +40,12 @@ tasks {
     }
 }
 
+tasks.withType(KotlinCompile::class).all {
+    kotlinOptions {
+        freeCompilerArgs = freeCompilerArgs + listOf("-opt-in=org.jetbrains.dokka.InternalDokkaApi",)
+    }
+}
+
 registerDokkaArtifactPublication("dokkaCore") {
     artifactId = "dokka-core"
 }
diff --git a/core/src/main/kotlin/InternalDokkaApi.kt b/core/src/main/kotlin/InternalDokkaApi.kt
new file mode 100644
index 00000000..4389bf7b
--- /dev/null
+++ b/core/src/main/kotlin/InternalDokkaApi.kt
@@ -0,0 +1,21 @@
+package org.jetbrains.dokka
+
+
+/**
+ * Marks declarations that are **internal** to Dokka core artifact.
+ * It means that this API is marked as **public** either for historical or technical reasons.
+ * It is not intended to be used outside of the Dokka project, has no behaviour guarantees,
+ * and may lack clear semantics, documentation and backward compatibility.
+ *
+ * If you are using such API, it is strongly suggested to migrate from it in order
+ * to keep backwards compatibility with future Dokka versions.
+ * Typically, the easiest way to do so is to copy-paste the corresponding utility into
+ * your own project.
+ */
+@RequiresOptIn(
+    level = RequiresOptIn.Level.ERROR,
+    message = "This is an internal Dokka API not intended for public use"
+)
+@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.FIELD)
+@Retention(AnnotationRetention.BINARY)
+public annotation class InternalDokkaApi()
diff --git a/core/src/main/kotlin/utilities/SelfRepresentingSingletonSet.kt b/core/src/main/kotlin/utilities/SelfRepresentingSingletonSet.kt
index d384bda4..c29d1b2a 100644
--- a/core/src/main/kotlin/utilities/SelfRepresentingSingletonSet.kt
+++ b/core/src/main/kotlin/utilities/SelfRepresentingSingletonSet.kt
@@ -1,5 +1,8 @@
 package org.jetbrains.dokka.utilities
 
+import org.jetbrains.dokka.*
+
+@InternalDokkaApi
 interface SelfRepresentingSingletonSet<T : SelfRepresentingSingletonSet<T>> : Set<T> {
     override val size: Int get() = 1