Configure default documentedVisibilities for perPackageOptions

Fix KT-70872
Kotlin · Sep 18, 2024 · c6626b2 · c6626b2
1 parent cd01d32
commit c6626b2
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 8 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
@@ -210,11 +210,11 @@ constructor(
  }
 
  perPackageOptions.configureEach {
- this.matchingRegex.convention(".*")
- this.suppress.convention(this@dss.suppress)
- this.skipDeprecated.convention(this@dss.skipDeprecated)
- this.reportUndocumented.convention(this@dss.reportUndocumented)
- this.documentedVisibilities.convention(this@dss.documentedVisibilities)
+ matchingRegex.convention(".*")
+ 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
@@ -20,6 +20,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,7 +214,9 @@ 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.
+ *
+ * Use the [perPackageOptions] function to add a new item.
  *
  * @see DokkaPackageOptionsSpec for details
  */

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)
+ }
+ }
+ }
  }
  }
 })