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]

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!