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/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceSetSpec.kt index 4277192b2d..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,12 +263,12 @@ 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:InputFiles - @get:PathSensitive(PathSensitivity.RELATIVE) + @get:Internal // tracked by `inputSourceFiles` abstract val suppressedFiles: ConfigurableFileCollection + /** * Whether to document/analyze generated files. * @@ -444,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 { /** 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")) } } 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() + ) + } +}