Fix suppressGeneratedFiles was unused

[whyoleg]

Fixes #4217

[whyoleg]

@adam-enko, MultiModuleFunctionalTest fails for some reason because of should have outcome FROM_CACHE, but was SUCCESS on CI.
Locally, everything is fine. Do you know what the reason might be?

[adam-enko]

Using the paths as an input will break relocatable build-cache. This could be the cause of the CI failure.

org.jetbrains.dokka.gradle.MultiModuleFunctionalTest > Gradle caching > Gradle caching build cache relocation > Gradle caching build cache relocation relocated project > org.jetbrains.dokka.gradle.MultiModuleFunctionalTest.Gradle caching build cache relocation relocated project should load all generation tasks from cache FAILED
    io.kotest.assertions.MultiAssertionError at MultiModuleFunctionalTest.kt:279

[whyoleg]

Hm, what would be a better way than to rely on paths, but not to rely on the content of the files? Relativize them?

The issue with relying on the content, apart from the fact that we don't care about the content here, is that in that case, our test starts to fail because we now declare an implicit dependency on some files generated by AGP. And that's correct.

[adam-enko]

I think this needs to be fixed another way.

It doesn't make sense for suppressedFiles to be @InputFiles. This will make the Dokka tasks sensitive to changes in files that don't affect the output. Changes in suppressed files should be ignored. If only suppressed files change then the Dokka tasks should be loaded from cache.

It's similar for sourceRoots - it will track the suppressed files, which causes cache misses.

Instead of users supplying the files to exclude, I think it makes sense for them to pass in glob patterns for files to suppress.

Something like this:

abstract class DokkaSourceSetSpec {

    // ...

    @get:Internal // tracked by `actualFiles()`
    abstract val sourceRoots: ConfigurableFileCollection
    
    @get:Internal
    @Deprecated("Use `suppressedFilesPatterns` instead")
    abstract val suppressedFiles: ConfigurableFileCollection

    /** Glob patterns, relative to each source root. */
    @get:Internal // tracked by `actualFiles()`
    abstract val suppressedFilesPatterns: SetProperty<String>

    // this is just for task input tracking, it's not used anywhere
    @InputFiles
    @IgnoreEmptyDirectories
    @PathSensitive(PathSensitivity.RELATIVE)
    fun actualFiles(): FileCollection {
        return objects.fileCollection().from(
            sourceRoots
                .asFileTree
                .matching {
                    suppressedFilesPatterns.orNull?.forEach { pattern ->
                        exclude(pattern)
                    }
                }
                .files
                .sorted()
        )
    }

    // TODO Use this in DokkaSourceSetBuilder instead of `val suppressedFiles`
    @Internal
    fun suppressedFiles(): FileCollection {
        return objects.fileCollection().from(
            sourceRoots
                .asFileTree
                .matching {
                    suppressedFilesPatterns.orNull?.forEach { pattern ->
                        include(pattern)
                    }
                }
                .files
                .sorted()
        )
    }

There's also a new 'generated sources' option in KGP. DGP could integrate with that somehow...

https://youtrack.jetbrains.com/issue/KT-45161/Gradle-Support-registering-generated-sources-with-the-Kotlin-model#focus=Comments-27-12807139.0-0

[whyoleg]

Hm, yes, that looks like a nice idea. The only problem I see is that in that case, we will provide all files separately to Dokka instead of just roots, which might affect performance inside Dokka, and will, for sure, make the configuration (JSON) much more verbose.

At this moment, I would really avoid such a significant change.

The new KGP API is available only in 2.3.0 (which does not even have a stable version), and is not yet adopted by any third-party plugins, but yes, we can integrate it with the suppressGeneratedFiles flag.

For patterns (or regex), there is #4106.

[adam-enko]

Hm, yes, that looks like a nice idea. The only problem I see is that in that case, we will provide all files separately to Dokka instead of just roots, which might affect performance inside Dokka, and will, for sure, make the configuration (JSON) much more verbose.

I don't think my proposal would affect that. sourceRoots would still be converted directly. The only change would be exposing the Gradle inputs.

[whyoleg]

I don't think my proposal would affect that. sourceRoots would still be converted directly. The only change would be exposing the Gradle inputs.

Oh, sorry, my bad! Looks like I misinterpreted that. Thanks!
I will try to implement the proposed solution then!