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

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;

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"
 }

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()

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