Revise developer guides documentation (#2523)

3 files changed, 79 insertions, 0 deletions

diff --git a/examples/plugin/hide-internal-api/src/main/kotlin/org/example/dokka/plugin/HideInternalApiPlugin.kt b/examples/plugin/hide-internal-api/src/main/kotlin/org/example/dokka/plugin/HideInternalApiPlugin.kt
new file mode 100644
index 00000000..e0edac4b
--- /dev/null
+++ b/examples/plugin/hide-internal-api/src/main/kotlin/org/example/dokka/plugin/HideInternalApiPlugin.kt
@@ -0,0 +1,34 @@
+package org.example.dokka.plugin
+
+import org.jetbrains.dokka.base.DokkaBase
+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
+import org.jetbrains.dokka.plugability.DokkaPlugin
+
+class HideInternalApiPlugin : DokkaPlugin() {
+    val myFilterExtension by extending {
+        plugin<DokkaBase>().preMergeDocumentableTransformer providing ::HideInternalApiTransformer
+    }
+}
+
+class HideInternalApiTransformer(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) {
+
+    override fun shouldBeSuppressed(d: Documentable): Boolean {
+        val annotations: List<Annotations.Annotation> =
+            (d as? WithExtraProperties<*>)
+                ?.extra
+                ?.allOfType<Annotations>()
+                ?.flatMap { it.directAnnotations.values.flatten() }
+                ?: emptyList()
+
+        return annotations.any { isInternalAnnotation(it) }
+    }
+
+    private fun isInternalAnnotation(annotation: Annotations.Annotation): Boolean {
+        return annotation.dri.packageName == "org.jetbrains.dokka.internal.test"
+                && annotation.dri.classNames == "Internal"
+    }
+}
diff --git a/examples/plugin/hide-internal-api/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin b/examples/plugin/hide-internal-api/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin
new file mode 100644
index 00000000..a179d0c9
--- /dev/null
+++ b/examples/plugin/hide-internal-api/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin
@@ -0,0 +1 @@
+org.example.dokka.plugin.HideInternalApiPlugin
diff --git a/examples/plugin/hide-internal-api/src/test/kotlin/org/example/dokka/plugin/HideInternalApiPluginTest.kt b/examples/plugin/hide-internal-api/src/test/kotlin/org/example/dokka/plugin/HideInternalApiPluginTest.kt
new file mode 100644
index 00000000..f98208d0
--- /dev/null
+++ b/examples/plugin/hide-internal-api/src/test/kotlin/org/example/dokka/plugin/HideInternalApiPluginTest.kt
@@ -0,0 +1,44 @@
+package org.example.dokka.plugin
+
+import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import org.junit.Test
+import kotlin.test.assertEquals
+
+class HideInternalApiPluginTest : BaseAbstractTest() {
+    @Test
+    fun `should hide annotated functions`() {
+        val configuration = dokkaConfiguration {
+            sourceSets {
+                sourceSet {
+                    sourceRoots = listOf("src/main/kotlin/basic/Test.kt")
+                }
+            }
+        }
+        val hideInternalPlugin = HideInternalApiPlugin()
+
+        testInline(
+            """
+            |/src/main/kotlin/basic/Test.kt
+            |package org.jetbrains.dokka.internal.test
+            |
+            |annotation class Internal
+            |
+            |fun shouldBeVisible() {}
+            |
+            |@Internal
+            |fun shouldBeExcludedFromDocumentation() {}
+        """.trimMargin(),
+            configuration = configuration,
+            pluginOverrides = listOf(hideInternalPlugin)
+        ) {
+            preMergeDocumentablesTransformationStage = { modules ->
+                val testModule = modules.single { it.name == "root" }
+                val testPackage = testModule.packages.single { it.name == "org.jetbrains.dokka.internal.test" }
+
+                val packageFunctions = testPackage.functions
+                assertEquals(1, packageFunctions.size)
+                assertEquals("shouldBeVisible", packageFunctions[0].name)
+            }
+        }
+    }
+}