are breaking changes still possible even though th...

# dokka

[solonovamax]

are breaking changes still possible even though the dokka gradle plugin is in beta?

because, imo, DokkaSourceSetSpec.suppressedFiles (and tbh DokkaSourceSetSpec.includes and DokkaSourceSetSpec.samples as well) should be ConfigurableFileTree instead of ConfigurableFileCollection

I mention this in this issue I made: https://github.com/Kotlin/dokka/issues/3863

[Adam Semenenko]

hey, thanks for looking into it! We can definitely look into breaking changes, and I'm glad you sent a message so we can discuss it further.

I agree that easily adding all files in a directory would be useful.

I haven't looked into the pro/cons of using a ConfigurableFileCollection or ConfigurableFileTree, but my initial thoughts are:

I prefer CFCs because the contents are more explicit, and FileTrees have some downsides (e.g. they cannot contain directories, and they cause cache misses because the order is non-deterministic). So I'd prefer using CFC for all API surfaces to be consistent.

Also, I wonder, what would happen if you tried adding a FileTree to includes?

//includes.from(file("dokka"))
includes.from(fileTree("dokka"))

Does that produce the result you need?

[solonovamax]

for me, wrapping it directly in a fileTree() did not work, as I was using something roughly similar to:

val processDokkaIncludes by tasks.registering(ProcessResources::class) {
    into(TODO("output"))
    from(TODO("input")) {
        expand("replacement" to "result")
    }
}
dokka {
    dokkaSourceSets.configureEach {
        includes.from(processDokkaIncludes)
    }
}

here, from(processDokkaIncludes) resolves to grabbing the output directory of the processDokkaIncludes task

so, the PR I submitted will properly resolve this, whereas fileTree(processDokkaIncludes) results in an error. the docs indicate that fileTree() will resolve files the same as file(), which does not resolve tasks.

however, I did just check the docs for ConfigurableFileTree and it seems that it also resolves its from() argument the same as file(), whereas ConfigurableFileCollection will resolve its from() argument according to files() (note: the "s" at the end), which does resolve tasks.

so, perhaps the best way to do this might instead be to use a CopySpec, for which Project.copySpec exists.

also, since the input to the includes/etc. is transformed using .files, I don't think that it will actually run the tasks providing the files if not explicitly added to the dependsOn for a given task, whereas if CopySpec were used and added as an @Input on the gradle task, it would run the dependant tasks (edit: I checked, and it is not preserving the task dependencies properly, when extra transforms are applied such as includes.from(fileTree(processDokkaIncludes.map { it.destinationDir })), however if you are only doing includes.from(processDokkaIncludes), then it will preserve task dependencies.

[solonovamax]

for me personally however, I could do

includes.from(fileTree(processDokkaIncludes.map { it.destinationDir }))

as file() will resolve a Provider<File>

[solonovamax]

but, I still do think that the use of .asFileTree.files instead of .files in the DokkaSourceSetBuilder is a good intermediary fix, until a better class instead of ConfigurableFileCollection can be used.

[solonovamax]

I think that making it a CopySpec instead might be a good idea, tbh
especially since it allows users to process the inputs to all of those without having to create a dedicated task for it

[Adam Semenenko]

I checked, and it is not preserving the task dependencies properly, when extra transforms are applied such as includes.from(fileTree(processDokkaIncludes.map { it.destinationDir })),

Yeah, unfortunately that will make Gradle forget about the task dependency. What about if you put the fileTree() inside the map {} though?

includes.from(processDokkaIncludes.map { fileTree(it.destinationDir) })

[Adam Semenenko]

I think that making it a CopySpec instead might be a good idea

From memory, CopySpec has problems when it's used as part of a plugin's DSL. It's difficult to instantiate, and IIRC it introduces problems with Configuration Cache.

I think you could try creating an instance of a CopySpec in your buildscript though, and passing it to includes.

[solonovamax]

What about if you put the fileTree() inside the map {} though?

99% sure that would not make a difference

[solonovamax]

It's difficult to instantiate

for instantiating it, you can just do Project.copySpec, actually (found this while looking at things for this plugin)

which is why I suggested it

[solonovamax]

though I meant more, making includes a CopySpec rather than a ConfigurableFileCollection