From 047a3bcd88a4c16e18c680ecb50fdf60472d081e Mon Sep 17 00:00:00 2001
From: Vsevolod Tolstopyatov <qwwdfsad@gmail.com>
Date: Fri, 17 Mar 2023 09:24:10 -0700
Subject: [PATCH] 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                             |  3 +++
 core/build.gradle.kts                         |  7 +++++++
 core/src/main/kotlin/InternalDokkaApi.kt      | 21 +++++++++++++++++++
 .../utilities/SelfRepresentingSingletonSet.kt |  3 +++
 4 files changed, 34 insertions(+)
 create mode 100644 core/src/main/kotlin/InternalDokkaApi.kt

diff --git a/core/api/core.api b/core/api/core.api
index d17c8cb486..ddd77a5c50 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 a51e3a62de..49b022ef97 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 0000000000..4389bf7be2
--- /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 d384bda4bd..c29d1b2afc 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