From 6cc31b07a75e9c1b478fd7b544eadc1faf6059a4 Mon Sep 17 00:00:00 2001 From: Adam <152864218+adam-enko@users.noreply.github.com> Date: Wed, 18 Sep 2024 11:19:30 +0200 Subject: [PATCH] Configure default documentedVisibilities for perPackageOptions (#3799) * Configure default documentedVisibilities for perPackageOptions Fix KT-70872 * remove unused annotation --- .../src/main/kotlin/DokkaBasePlugin.kt | 1 + .../parameters/DokkaPackageOptionsSpec.kt | 3 +- .../engine/parameters/DokkaSourceSetSpec.kt | 6 ++- .../src/test/kotlin/DokkaPluginTest.kt | 38 ++++++++++++++++++- 4 files changed, 42 insertions(+), 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 index 38229ae37d..989d0213d6 100644 --- 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/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaPackageOptionsSpec.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaPackageOptionsSpec.kt index fb297a6336..91239c562f 100644 --- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaPackageOptionsSpec.kt +++ b/dokka-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 index 2f4d3ef975..92e16931d9 100644 --- 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 /** - * 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 diff --git a/dokka-runners/dokka-gradle-plugin/src/test/kotlin/DokkaPluginTest.kt b/dokka-runners/dokka-gradle-plugin/src/test/kotlin/DokkaPluginTest.kt index f1f7b51f89..c30cbe3a89 100644 --- 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() - 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) + } + } + } } } })