Fix suppressGeneratedFiles was unused (#4348)

Co-authored-by: Adam Semenenko <152864218+adam-enko@users.noreply.github.com>

Author: whyoleg

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)

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,17 @@ constructor(
     abstract val noJdkLink: Property<Boolean>
     //endregion
 
+    // this is just for task input tracking
+    @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 {
 
         /**

dokka-runners/dokka-gradle-plugin/src/test/kotlin/engine/parameters/DokkaSourceSetSpecTest.kt

@@ -4,8 +4,12 @@
 package org.jetbrains.dokka.gradle.engine.parameters
 
 import io.kotest.core.spec.style.FunSpec
+import io.kotest.core.test.TestScope
+import io.kotest.inspectors.shouldForAll
 import io.kotest.matchers.collections.shouldBeEmpty
+import io.kotest.matchers.collections.shouldContainExactly
 import io.kotest.matchers.collections.shouldContainExactlyInAnyOrder
+import io.kotest.matchers.file.shouldBeAFile
 import io.kotest.matchers.shouldBe
 import org.gradle.api.Project
 import org.gradle.kotlin.dsl.apply
@@ -16,6 +20,11 @@ import org.jetbrains.dokka.gradle.DokkaPlugin
 import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier.Public
 import org.jetbrains.dokka.gradle.utils.create_
 import org.jetbrains.dokka.gradle.utils.enableV2Plugin
+import java.nio.file.Path
+import kotlin.io.path.Path
+import kotlin.io.path.createDirectories
+import kotlin.io.path.relativeTo
+import kotlin.io.path.writeText
 
 class DokkaSourceSetSpecTest : FunSpec({
 
@@ -39,7 +48,7 @@ class DokkaSourceSetSpecTest : FunSpec({
             dss.displayName.orNull shouldBe "foo"
         }
         test("documentedVisibilities") {
-            dss.documentedVisibilities.orNull.shouldContainExactlyInAnyOrder(Public)
+            dss.documentedVisibilities.orNull.shouldContainExactly(Public)
         }
         test("enableAndroidDocumentationLink") {
             dss.enableAndroidDocumentationLink.orNull shouldBe false
@@ -53,7 +62,7 @@ class DokkaSourceSetSpecTest : FunSpec({
         test("externalDocumentationLinks") {
             dss.externalDocumentationLinks
                 .map { it.run { "$name enabled:${enabled.orNull} url:${url.orNull} packageList:${packageListUrl.orNull}" } }
-                .shouldContainExactlyInAnyOrder(
+                .shouldContainExactly(
                     "androidSdk enabled:false url:https://developer.android.com/reference/kotlin/ packageList:https://developer.android.com/reference/kotlin/package-list",
                     "androidX enabled:false url:https://developer.android.com/reference/kotlin/ packageList:https://developer.android.com/reference/kotlin/androidx/package-list",
                     "jdk enabled:true url:https://docs.oracle.com/en/java/javase/11/docs/api/ packageList:https://docs.oracle.com/en/java/javase/11/docs/api/element-list",
@@ -107,7 +116,10 @@ class DokkaSourceSetSpecTest : FunSpec({
             dss.suppressGeneratedFiles.orNull shouldBe true
         }
         test("suppressedFiles") {
-            dss.suppressedFiles.shouldBeEmpty()
+            dss.suppressedFiles.toList() shouldBe listOf(project.file("build/generated"))
+        }
+        test("inputSourceFiles") {
+            dss.inputSourceFiles.shouldBeEmpty() // because `sourceRoots` is empty
         }
     }
 
@@ -141,6 +153,165 @@ class DokkaSourceSetSpecTest : FunSpec({
             }
         }
     }
+
+    context("DokkaSourceSetSpec inputSourceFiles ->") {
+
+        val project = createProject()
+
+        val projectDir = project.projectDir.toPath()
+        fun Path.createClass(name: String) {
+            createDirectories()
+            resolve("$name.kt").writeText("class $name")
+        }
+
+        val mainSourceDir =
+            projectDir.resolve("src/main/kotlin").apply {
+                resolve("com/example").apply {
+                    createClass("MainCls")
+                    resolve("sub").apply {
+                        createClass("Sub1MainCls")
+                        createClass("Sub2MainCls")
+                    }
+                }
+            }
+        val generatedSrcDir =
+            projectDir.resolve("build/generated/kotlin").apply {
+                createClass("BuildGenCls")
+                resolve("sub").apply {
+                    createClass("Sub1BuildGenCls")
+                    createClass("Sub2BuildGenCls")
+                }
+            }
+        val customGeneratedSrcDir =
+            projectDir.resolve("src/customGenerated/kotlin").apply {
+                createClass("CustomGenCls")
+                resolve("sub").apply {
+                    createClass("Sub1CustomGenCls")
+                    createClass("Sub2CustomGenCls")
+                }
+            }
+
+        fun TestScope.createDss(): DokkaSourceSetSpec {
+            val dss = project.createDokkaSourceSetSpec(testCase.name.testName)
+            dss.sourceRoots.from(mainSourceDir, generatedSrcDir, customGeneratedSrcDir)
+            return dss
+        }
+
+        fun DokkaSourceSetSpec.inputSourceFilesToRelativePaths(): List<Path> =
+            inputSourceFiles.map { it.toPath().relativeTo(projectDir) }
+
+        test("build/generated should be excluded by default") {
+            val dss = createDss()
+            dss.inputSourceFilesToRelativePaths() shouldContainExactlyInAnyOrder listOf(
+                Path("src/customGenerated/kotlin/CustomGenCls.kt"),
+                Path("src/customGenerated/kotlin/sub/Sub1CustomGenCls.kt"),
+                Path("src/customGenerated/kotlin/sub/Sub2CustomGenCls.kt"),
+                Path("src/main/kotlin/com/example/MainCls.kt"),
+                Path("src/main/kotlin/com/example/sub/Sub1MainCls.kt"),
+                Path("src/main/kotlin/com/example/sub/Sub2MainCls.kt"),
+            )
+        }
+        test("when suppressGeneratedFiles is set to false, expect all source files are included") {
+            val dss = createDss()
+            dss.suppressGeneratedFiles.set(false)
+            dss.inputSourceFilesToRelativePaths() shouldContainExactlyInAnyOrder listOf(
+                Path("build/generated/kotlin/BuildGenCls.kt"),
+                Path("build/generated/kotlin/sub/Sub1BuildGenCls.kt"),
+                Path("build/generated/kotlin/sub/Sub2BuildGenCls.kt"),
+                Path("src/customGenerated/kotlin/CustomGenCls.kt"),
+                Path("src/customGenerated/kotlin/sub/Sub1CustomGenCls.kt"),
+                Path("src/customGenerated/kotlin/sub/Sub2CustomGenCls.kt"),
+                Path("src/main/kotlin/com/example/MainCls.kt"),
+                Path("src/main/kotlin/com/example/sub/Sub1MainCls.kt"),
+                Path("src/main/kotlin/com/example/sub/Sub2MainCls.kt"),
+            )
+        }
+        test("input source files should only contain files, not directories") {
+            val dss = createDss()
+            dss.suppressGeneratedFiles.set(false)
+            dss.inputSourceFiles.files.shouldForAll { it.shouldBeAFile() }
+        }
+        test("expect files can be excluded by exact path") {
+            val dss = createDss()
+            dss.suppressGeneratedFiles.set(false)
+            dss.suppressedFiles.from(
+                "build/generated/kotlin/sub/Sub1BuildGenCls.kt",
+                "src/customGenerated/kotlin/sub/Sub1CustomGenCls.kt",
+                "src/main/kotlin/com/example/sub/Sub1MainCls.kt",
+            )
+            dss.inputSourceFilesToRelativePaths() shouldContainExactlyInAnyOrder listOf(
+                Path("build/generated/kotlin/BuildGenCls.kt"),
+                Path("build/generated/kotlin/sub/Sub2BuildGenCls.kt"),
+                Path("src/customGenerated/kotlin/CustomGenCls.kt"),
+                Path("src/customGenerated/kotlin/sub/Sub2CustomGenCls.kt"),
+                Path("src/main/kotlin/com/example/MainCls.kt"),
+                Path("src/main/kotlin/com/example/sub/Sub2MainCls.kt"),
+            )
+        }
+        test("expect files can be excluded by base directories") {
+            val dss = createDss()
+            dss.suppressGeneratedFiles.set(false)
+            dss.suppressedFiles.from(
+                "build/",
+                "src/",
+            )
+            dss.inputSourceFilesToRelativePaths().shouldBeEmpty()
+        }
+        test("expect files can be excluded by sub directories") {
+            val dss = createDss()
+            dss.suppressGeneratedFiles.set(false)
+            dss.suppressedFiles.from(
+                "build/generated/kotlin/sub/",
+                "src/customGenerated/kotlin/sub/",
+                "src/main/kotlin/com/example/sub/",
+            )
+            dss.inputSourceFilesToRelativePaths() shouldContainExactlyInAnyOrder listOf(
+                Path("build/generated/kotlin/BuildGenCls.kt"),
+                Path("src/customGenerated/kotlin/CustomGenCls.kt"),
+                Path("src/main/kotlin/com/example/MainCls.kt"),
+            )
+        }
+        test("expect nested files can be excluded") {
+            val dss = createDss()
+            dss.suppressGeneratedFiles.set(false)
+            dss.suppressedFiles.from(
+                "build/generated/kotlin/sub/",
+                "src/customGenerated/kotlin/sub/",
+                "src/main/kotlin/com/example/sub/",
+            )
+            dss.inputSourceFilesToRelativePaths() shouldContainExactlyInAnyOrder listOf(
+                Path("build/generated/kotlin/BuildGenCls.kt"),
+                Path("src/customGenerated/kotlin/CustomGenCls.kt"),
+                Path("src/main/kotlin/com/example/MainCls.kt"),
+            )
+        }
+        test("expect suppressGeneratedFiles and suppressedFiles (by specific files) exclude all generated and specified files") {
+            val dss = createDss()
+            dss.suppressGeneratedFiles.set(true)
+            dss.suppressedFiles.from(
+                "src/customGenerated/kotlin/sub/Sub1CustomGenCls.kt",
+                "src/customGenerated/kotlin/sub/Sub2CustomGenCls.kt",
+                "src/main/kotlin/com/example/sub/Sub1MainCls.kt",
+                "src/main/kotlin/com/example/sub/Sub2MainCls.kt",
+            )
+            dss.inputSourceFilesToRelativePaths() shouldContainExactlyInAnyOrder listOf(
+                Path("src/customGenerated/kotlin/CustomGenCls.kt"),
+                Path("src/main/kotlin/com/example/MainCls.kt"),
+            )
+        }
+        test("expect suppressGeneratedFiles and suppressedFiles (by directories) exclude all generated and specified files") {
+            val dss = createDss()
+            dss.suppressGeneratedFiles.set(true)
+            dss.suppressedFiles.from(
+                "src/customGenerated/kotlin/",
+            )
+            dss.inputSourceFilesToRelativePaths() shouldContainExactlyInAnyOrder listOf(
+                Path("src/main/kotlin/com/example/MainCls.kt"),
+                Path("src/main/kotlin/com/example/sub/Sub1MainCls.kt"),
+                Path("src/main/kotlin/com/example/sub/Sub2MainCls.kt"),
+            )
+        }
+    }
 }) {
     companion object {
         private fun createProject(): Project {