From 928a351c09f53a301e03bf970210d60d99f4d24e Mon Sep 17 00:00:00 2001 From: Oleg Yukhnevich Date: Fri, 14 Nov 2025 19:05:09 +0200 Subject: [PATCH 1/4] Fix `suppressGeneratedFiles` was unused --- .../src/main/kotlin/DokkaBasePlugin.kt | 9 ++ .../SuppressGeneratedFilesFunctionalTest.kt | 131 ++++++++++++++++++ 2 files changed, 140 insertions(+) create mode 100644 dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/SuppressGeneratedFilesFunctionalTest.kt 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 3b9a7ee79f..b308e4a2d2 100644 --- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt +++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt @@ -208,6 +208,15 @@ constructor( sourceSetScope.convention(sourceSetScopeConvention) suppressGeneratedFiles.convention(true) + suppressedFiles.from( + suppressGeneratedFiles.map { suppressGenerated -> + if (suppressGenerated) { + layout.buildDirectory.dir("generated") + } else { + objects.fileCollection() + } + } + ) sourceLinks.configureEach { localDirectory.convention(layout.projectDirectory) diff --git a/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/SuppressGeneratedFilesFunctionalTest.kt b/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/SuppressGeneratedFilesFunctionalTest.kt new file mode 100644 index 0000000000..2a29c6d305 --- /dev/null +++ b/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/SuppressGeneratedFilesFunctionalTest.kt @@ -0,0 +1,131 @@ +/* + * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ +package org.jetbrains.dokka.gradle + +import io.kotest.core.spec.style.FunSpec +import io.kotest.matchers.paths.shouldExist +import io.kotest.matchers.string.shouldContain +import io.kotest.matchers.string.shouldNotContain +import org.jetbrains.dokka.gradle.internal.DokkaConstants.DOKKA_VERSION +import org.jetbrains.dokka.gradle.utils.* +import java.nio.file.Path +import kotlin.io.path.readText + +class SuppressGeneratedFilesFunctionalTest : FunSpec({ + + context("suppressGeneratedFiles") { + + test("when suppressGeneratedFiles is true, generated files should be suppressed") { + val project = createProject(suppressGeneratedFiles = true) + + project.runner + .addArguments( + ":dokkaGeneratePublicationHtml", + "--rerun-tasks", + "--stacktrace", + ) + .build { + val htmlContent = project.projectDir + .resolve("build/dokka/html/suppress-generated-files-true/[root]/index.html") + .also(Path::shouldExist) + .readText() + htmlContent shouldContain "MyClass" + htmlContent shouldNotContain "GeneratedClass" + htmlContent shouldNotContain "GeneratedJavaClass" + } + } + + test("when suppressGeneratedFiles is false, generated files should be documented") { + val project = createProject(suppressGeneratedFiles = false) + + project.runner + .addArguments( + ":dokkaGeneratePublicationHtml", + "--rerun-tasks", + "--stacktrace", + ) + .build { + val htmlContent = project.projectDir + .resolve("build/dokka/html/suppress-generated-files-false/[root]/index.html") + .also(Path::shouldExist) + .readText() + htmlContent shouldContain "MyClass" + htmlContent shouldContain "GeneratedClass" + htmlContent shouldContain "GeneratedJavaClass" + } + } + } +}) + +private fun createProject( + suppressGeneratedFiles: Boolean +): GradleProjectTest = gradleKtsProjectTest("suppress-generated-files-$suppressGeneratedFiles") { + buildGradleKts = """ + |plugins { + | kotlin("jvm") version embeddedKotlinVersion + | id("org.jetbrains.dokka") version "$DOKKA_VERSION" + |} + | + |dokka { + | dokkaSourceSets.configureEach { + | suppressGeneratedFiles.set(${suppressGeneratedFiles}) + | // emulate generated sources added, for example by KSP + | sourceRoots.from("build/generated") + | } + |} + |""".trimMargin() + + dir("src/main/kotlin") { + createKotlinFile( + "MyClass.kt", + """ + |/** + | * A regular class that should be documented + | */ + |class MyClass { + | /** + | * A function that should be documented + | */ + | fun regularFunction() = "Hello" + |} + |""".trimMargin() + ) + } + + dir("build/generated/ksp/main") { + createKotlinFile( + "GeneratedClass.kt", + """ + |/** + | * A generated class that should NOT be documented + | */ + |class GeneratedClass { + | /** + | * A generated function that should NOT be documented + | */ + | fun generatedFunction() = "Generated" + |} + |""".trimMargin() + ) + } + + dir("build/generated/apt/java/main") { + createFile( + "GeneratedJavaClass.java", + """ + |/** + | * A generated Java class that should NOT be documented + | */ + |public class GeneratedJavaClass { + | /** + | * A generated method that should NOT be documented + | */ + | public String generatedMethod() { + | return "Generated Java"; + | } + |} + |""".trimMargin() + ) + } +} From a4ec46c640d3a94ec40d87e31010c09c16295616 Mon Sep 17 00:00:00 2001 From: Oleg Yukhnevich Date: Fri, 21 Nov 2025 16:16:50 +0200 Subject: [PATCH 2/4] Fix test for default suppressedFiles value in DokkaSourceSetSpecTest --- .../src/test/kotlin/engine/parameters/DokkaSourceSetSpecTest.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dokka-runners/dokka-gradle-plugin/src/test/kotlin/engine/parameters/DokkaSourceSetSpecTest.kt b/dokka-runners/dokka-gradle-plugin/src/test/kotlin/engine/parameters/DokkaSourceSetSpecTest.kt index c7d9bc62ae..0fe7c11ea6 100644 --- a/dokka-runners/dokka-gradle-plugin/src/test/kotlin/engine/parameters/DokkaSourceSetSpecTest.kt +++ b/dokka-runners/dokka-gradle-plugin/src/test/kotlin/engine/parameters/DokkaSourceSetSpecTest.kt @@ -107,7 +107,7 @@ class DokkaSourceSetSpecTest : FunSpec({ dss.suppressGeneratedFiles.orNull shouldBe true } test("suppressedFiles") { - dss.suppressedFiles.shouldBeEmpty() + dss.suppressedFiles.toList() shouldBe listOf(project.file("build/generated")) } } From aaf55bb19b034450185cf2b33c17c5cc2a41a53c Mon Sep 17 00:00:00 2001 From: Oleg Yukhnevich Date: Fri, 21 Nov 2025 16:18:32 +0200 Subject: [PATCH 3/4] Make `suppressedFiles` input as just paths, we don't care about content here --- .../kotlin/engine/parameters/DokkaSourceSetSpec.kt | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) 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 4277192b2d..74eb723c43 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 @@ -265,10 +265,16 @@ constructor( * * Will be concatenated with generated files if [suppressGeneratedFiles] is set to `false`. */ - @get:InputFiles - @get:PathSensitive(PathSensitivity.RELATIVE) + @get:Internal abstract val suppressedFiles: ConfigurableFileCollection + /** + * We don't care about the content of those [suppressedFiles] as we use those only as paths to filter sources. + */ + @get:Input + internal val suppressedFilesInput: List + get() = suppressedFiles.map { it.path }.sorted() + /** * Whether to document/analyze generated files. * From 9ed0e73a566c5c0ddb4b3dedd156e0e6fe724d20 Mon Sep 17 00:00:00 2001 From: Oleg Yukhnevich Date: Wed, 26 Nov 2025 15:45:00 +0200 Subject: [PATCH 4/4] Make the Gradle input tracking machinery happy --- .../engine/parameters/DokkaSourceSetSpec.kt | 26 ++++++++++++------- 1 file changed, 16 insertions(+), 10 deletions(-) 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 74eb723c43..9eeb654051 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 @@ -5,6 +5,7 @@ package org.jetbrains.dokka.gradle.engine.parameters import org.gradle.api.* import org.gradle.api.file.ConfigurableFileCollection +import org.gradle.api.file.FileCollection import org.gradle.api.model.ObjectFactory import org.gradle.api.plugins.ExtensionAware import org.gradle.api.provider.Property @@ -177,8 +178,7 @@ constructor( * * By default, source roots are deduced from information provided by the Kotlin Gradle plugin. */ - @get:InputFiles - @get:PathSensitive(PathSensitivity.RELATIVE) + @get:Internal // tracked by `inputSourceFiles` abstract val sourceRoots: ConfigurableFileCollection /** @@ -263,17 +263,11 @@ constructor( * Directories or individual files that should be suppressed, meaning declarations from them * will be not documented. * - * Will be concatenated with generated files if [suppressGeneratedFiles] is set to `false`. + * Will be concatenated with generated files if [suppressGeneratedFiles] is set to `true`. */ - @get:Internal + @get:Internal // tracked by `inputSourceFiles` abstract val suppressedFiles: ConfigurableFileCollection - /** - * We don't care about the content of those [suppressedFiles] as we use those only as paths to filter sources. - */ - @get:Input - internal val suppressedFilesInput: List - get() = suppressedFiles.map { it.path }.sorted() /** * Whether to document/analyze generated files. @@ -450,6 +444,18 @@ constructor( abstract val noJdkLink: Property //endregion + // this is just for task input tracking, it's not used anywhere + @Suppress("unused") + @get:InputFiles + @get:IgnoreEmptyDirectories + @get:PathSensitive(PathSensitivity.RELATIVE) + internal val inputSourceFiles: FileCollection + get() = sourceRoots.asFileTree.filter { sourceFile -> + suppressedFiles.none { suppressedFile -> + sourceFile.startsWith(suppressedFile) + } + } + companion object { /**