Introduce InternalDokkaApi annotation (#2904)

* Introduce InternalDokkaApi annotation

Rationale:

dokka-core has a long history of bloating its API shape with utilities that were never intended to be public, and that may expose unwanted implementation details, as well as unwanted compatibility burdens.

Eventually, we would like to get rid of them (i.e. by making them internal), but first, it would be nice to provide users with an explicit message about it

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