[Bug] Dokka Does Not Accept Using Directories for the Includes Property

[solonovamax]

Describe the Bug

When setting the "includes" for dokka, it will not accept directories.

Expected Behaviour

Directories are accepted when doing

dokka {
    dokkaSourceSets.configureEach {
        includes.from(file("dokka")) // here, dokka is a directory containing multiple markdown files
    }
}

Actual Behaviour

An error is produced when the above code is used.

Environment

• Operating system: Linux
• Build tool: Gradle 8.10.1
• Dokka version: 2.0.0-Beta

Additional Information

The issue here is with the use of FileCollection.getFiles() on this line:

dokka/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/builders/DokkaSourceSetBuilder.kt

Line 77 in 7027da8

includes = spec.includes.files,

As-per the documentation:

Returns the contents of this collection as a Set. The contents of a file collection may change over time.
Note that this method returns File objects that represent locations on the file system. These File objects do not necessarily refer to regular files. Depending on the implementation of this file collection and how it has been configured, the returned set may contain directories, or missing files, or any other kind of file system element.

(emphasis my own)

Also, this same issue will apply to

• classpath
• samples
• suppressedFiles

The solution to this would be to instead use a FileTree:

// files
classpath = spec.classpath.asFileTree.files.toList(),
includes = spec.includes.asFileTree.files,
samples = spec.samples.asFileTree.files,
sourceRoots = spec.sourceRoots.files,
suppressedFiles = spec.suppressedFiles.asFileTree.files,

however, I do believe it would be beneficial to expose suppressedFiles as a ConfigurableFileTree rather than a ConfigurableFileCollection. This is because it allows filtering:

dokka {
    dokkaSourceSets.configureEach {
        suppressedFiles.apply {
            from("src")
            include("**/internal/**")
            exclude("**/api/**")
        }
    }
}

however, this would be a breaking api change. Unsure if breaking api changes would be possible for the beta.
I am going to submit a PR that changes it to use a file tree, however.

[adam-enko]

Discussed further in Slack: https://kotlinlang.slack.com/archives/C0F4UNJET/p1729054899938509 (archive)