Configure default documentedVisibilities for perPackageOptions (#3799)

* Configure default documentedVisibilities for perPackageOptions Fix KT-70872 * remove unused annotation
Kotlin · Sep 18, 2024 · 6cc31b0 · 6cc31b0
1 parent c9adb4a
commit 6cc31b0
Show file tree

Hide file tree

Showing 4 changed files with 42 additions and 6 deletions.
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt
@@ -214,6 +214,7 @@ constructor(
                 suppress.convention(false)
                 skipDeprecated.convention(false)
                 reportUndocumented.convention(false)
+                documentedVisibilities.convention(listOf(VisibilityModifier.Public))
             }
 
             externalDocumentationLinks {

diff --git a/...-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaPackageOptionsSpec.kt b/...-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaPackageOptionsSpec.kt
@@ -1,5 +1,3 @@
-@file:Suppress("FunctionName")
-
 /*
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
@@ -20,6 +18,7 @@ import java.io.Serializable
  * ```kotlin
  * tasks.dokkaHtml {
  *     dokkaSourceSets.configureEach {
+ *         // create a new perPackageOption
  *         perPackageOption {
  *             matchingRegex.set(".*internal.*")
  *             suppress.set(true)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt
@@ -214,9 +214,11 @@ constructor(
     abstract val sourceLinks: DomainObjectSet<DokkaSourceLinkSpec>
 
     /**
-     * Allows to customize documentation generation options on a per-package basis.
+     * Allows customising documentation generation options on a per-package basis.
      *
-     * @see DokkaPackageOptionsSpec for details
+     * Use the [perPackageOptions] function to add a new item.
+     *
+     * @see DokkaPackageOptionsSpec
      */
     @get:Nested
     abstract val perPackageOptions: DomainObjectSet<DokkaPackageOptionsSpec>

diff --git a/dokka-runners/dokka-gradle-plugin/src/test/kotlin/DokkaPluginTest.kt b/dokka-runners/dokka-gradle-plugin/src/test/kotlin/DokkaPluginTest.kt
@@ -3,13 +3,17 @@
  */
 package org.jetbrains.dokka.gradle
 
+import io.kotest.assertions.withClue
 import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.collections.shouldBeSingleton
+import io.kotest.matchers.collections.shouldContainExactly
 import io.kotest.matchers.shouldBe
 import io.kotest.matchers.string.shouldEndWith
 import org.gradle.kotlin.dsl.apply
 import org.gradle.kotlin.dsl.getByType
 import org.gradle.kotlin.dsl.hasPlugin
 import org.gradle.testfixtures.ProjectBuilder
+import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier
 import org.jetbrains.dokka.gradle.utils.create_
 import org.jetbrains.dokka.gradle.utils.enableV2Plugin
 
@@ -31,14 +35,14 @@ class DokkaPluginTest : FunSpec({
         project.plugins.hasPlugin(DokkaPlugin::class) shouldBe true
     }
 
-    context("Dokkatoo property conventions") {
+    context("Dokka property conventions") {
         val project = ProjectBuilder.builder().build()
             .enableV2Plugin()
         project.plugins.apply("org.jetbrains.dokka")
 
         val extension = project.extensions.getByType<DokkaExtension>()
 
-        context("DokkatooSourceSets") {
+        context("DokkaSourceSets") {
             val testSourceSet = extension.dokkaSourceSets.create_("Test") {
                 externalDocumentationLinks.create_("gradle") {
                     url("https://docs.gradle.org/7.6.1/javadoc")
@@ -80,6 +84,36 @@ class DokkaPluginTest : FunSpec({
                         .toString() shouldBe "https://docs.gradle.org/7.6.1/javadoc/package-list"
                 }
             }
+
+            context("perPackageOptions") {
+                test("new element should have expected convention values") {
+
+                    // perPackageOptions aren't named, so we can't create and fetch a specific element.
+                    // Instead, clear all other elements and create a new one, then fetch the first.
+                    testSourceSet.perPackageOptions.clear()
+                    testSourceSet.perPackageOption { }
+
+                    val perPackageOption = testSourceSet.perPackageOptions
+                        .shouldBeSingleton()
+                        .single()
+
+                    withClue("matchingRegex") {
+                        perPackageOption.matchingRegex.orNull shouldBe ".*"
+                    }
+                    withClue("suppress") {
+                        perPackageOption.suppress.orNull shouldBe false
+                    }
+                    withClue("skipDeprecated") {
+                        perPackageOption.skipDeprecated.orNull shouldBe false
+                    }
+                    withClue("reportUndocumented") {
+                        perPackageOption.reportUndocumented.orNull shouldBe false
+                    }
+                    withClue("documentedVisibilities") {
+                        perPackageOption.documentedVisibilities.orNull.shouldContainExactly(VisibilityModifier.Public)
+                    }
+                }
+            }
         }
     }
 })