Added dokka plugin for removal of internal declarations

Author: Mr3zee

build.gradle.kts

@@ -73,6 +73,10 @@ dokka {
     }
 }
 
+dependencies {
+    dokkaPlugin(libs.dokka.rpc.plugin)
+}
+
 configureProjectReport()
 configureNpm()
 configureApiValidation()

dokka-plugin/build.gradle.kts

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+plugins {
+    alias(libs.plugins.conventions.gradle.doctor)
+    id("build-util")
+    alias(libs.plugins.kotlin.jvm)
+}
+
+val rpcVersion: String = libs.versions.kotlinx.rpc.get()
+val kotlinLangVersion = libs.versions.kotlin.lang.get()
+
+group = "org.jetbrains.kotlinx"
+version = rpcVersion
+
+println("[Dokka Plugin] kotlinx.rpc project version: $version, Kotlin version: $kotlinLangVersion")
+
+kotlin {
+    jvmToolchain(8)
+}
+
+dependencies {
+    compileOnly(libs.dokka.core)
+    compileOnly(libs.dokka.base)
+
+    testImplementation(kotlin("test"))
+    testImplementation(libs.dokka.base)
+    testImplementation("org.jetbrains.dokka:dokka-test-api:${libs.versions.dokka.get()}")
+    testImplementation("org.jetbrains.dokka:dokka-base-test-utils:${libs.versions.dokka.get()}")
+    testImplementation("org.jetbrains.dokka:analysis-kotlin-symbols:${libs.versions.dokka.get()}")
+}

dokka-plugin/settings.gradle.kts

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+rootProject.name = "dokka-rpc-plugin"
+
+enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
+
+pluginManagement {
+    includeBuild("../gradle-conventions")
+    includeBuild("../gradle-conventions-settings")
+}
+
+plugins {
+    id("conventions-repositories")
+    id("conventions-version-resolution")
+    id("conventions-develocity")
+}

dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/AddDocsLinkPageTransformer.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.rpc.dokka
+
+import org.jetbrains.dokka.pages.RootPageNode
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.transformers.pages.PageTransformer
+
+class AddDocsLinkPageTransformer(private val context: DokkaContext) : PageTransformer {
+    override fun invoke(input: RootPageNode): RootPageNode = input
+}

dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/HideInternalRpcApiTransformer.kt

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.rpc.dokka
+
+import org.jetbrains.dokka.base.DokkaBaseConfiguration
+import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer
+import org.jetbrains.dokka.model.Annotations
+import org.jetbrains.dokka.model.Documentable
+import org.jetbrains.dokka.model.properties.WithExtraProperties
+import org.jetbrains.dokka.plugability.DokkaContext
+
+class HideInternalRpcApiTransformer(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) {
+    override fun shouldBeSuppressed(d: Documentable): Boolean {
+        DokkaBaseConfiguration
+        val annotations: List<Annotations.Annotation> =
+            (d as? WithExtraProperties<*>)
+                ?.extra
+                ?.allOfType<Annotations>()
+                ?.flatMap { it.directAnnotations.values.flatten() }
+                ?: emptyList()
+
+        return annotations.any { isInternalRpcAnnotation(it) }
+    }
+
+    private fun isInternalRpcAnnotation(annotation: Annotations.Annotation): Boolean {
+        return annotation.dri.packageName == "kotlinx.rpc.internal.utils"
+                && annotation.dri.classNames == "InternalRpcApi"
+    }
+}

dokka-plugin/src/main/kotlin/kotlinx/rpc/dokka/RpcDokkaPlugin.kt

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.rpc.dokka
+
+import org.jetbrains.dokka.CoreExtensions
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
+
+@Suppress("unused")
+class RpcDokkaPlugin : DokkaPlugin() {
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement() = PluginApiPreviewAcknowledgement
+
+    val rpcInternalApiTransformer by extending {
+        plugin<DokkaBase>().preMergeDocumentableTransformer providing ::HideInternalRpcApiTransformer
+    }
+
+    val pageTransformer by extending {
+        CoreExtensions.pageTransformer providing ::AddDocsLinkPageTransformer
+    }
+}

dokka-plugin/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin

@@ -0,0 +1,5 @@
+#
+# Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+#
+
+kotlinx.rpc.dokka.RpcDokkaPlugin

dokka-plugin/src/test/kotlin/kotlinx/rpc/dokka/HideInternalRpcApiPluginTest.kt

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.rpc.dokka
+
+import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class HideInternalRpcApiPluginTest : BaseAbstractTest() {
+    @Test
+    fun `should hide annotated functions`() {
+        val configuration = dokkaConfiguration {
+            sourceSets {
+                sourceSet {
+                    sourceRoots = listOf("src/main/kotlin/basic/Test.kt")
+                }
+            }
+        }
+
+        testInline(
+            """
+            |/src/main/kotlin/basic/Test.kt
+            |package kotlinx.rpc.internal.utils
+            |
+            |annotation class InternalRpcApi
+            |
+            |fun shouldBeVisible() {}
+            |
+            |@InternalRpcApi
+            |fun shouldBeExcludedFromDocumentation() {}
+        """.trimMargin(),
+            configuration = configuration,
+            pluginOverrides = listOf(RpcDokkaPlugin())
+        ) {
+            preMergeDocumentablesTransformationStage = { modules ->
+                val testModule = modules.single { it.name == "root" }
+                val testPackage = testModule.packages.single { it.name == "kotlinx.rpc.internal.utils" }
+
+                val packageFunctions = testPackage.functions
+                assertEquals(1, packageFunctions.size)
+                assertEquals("shouldBeVisible", packageFunctions[0].name)
+            }
+        }
+    }
+}

gradle-conventions/common/src/main/kotlin/util/dokka.kt

@@ -51,6 +51,8 @@ fun Project.applyDokka() {
         }
     }
 
+    dependencies.add("dokkaPlugin", libs.dokka.rpc.plugin)
+
     val thisProject = project
 
     rootProject.configurations.matching { it.name == "dokka" }.all {

settings.gradle.kts

@@ -32,6 +32,7 @@ plugins {
 
 dependencyResolutionManagement {
     includeBuild("compiler-plugin")
+    includeBuild("dokka-plugin")
 }
 
 includePublic(":bom")