Dokka Generator does not remove deleted files

[aSemy]

Describe the bug

If I delete classes in a subproject, Dokka does not delete the files in the aggregated publication.

The files are not visible in the HMTL (I presume because pages.json is updated, so even if the files are still present then they are not shown in the HTML navigation).

Expected behaviour

Dokka Generator should delete documentation for files that have been deleted.

To Reproduce

1. checkout Dokka

2. cd examples/gradle/dokka-multimodule-example

3. ./gradlew dokkaHtmlMultiModule

4. As expected, build/dokka/htmlMultiModule/childProjectB only contains one documented class, ChildProjectBClass

   

5. Create a new class, ./parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass2.kt

   package demo
   
   /**
    * Class defined in child module b
    */
   class ChildProjectBClass2

6. Re-run ./gradlew dokkaHtmlMultiModule

7. As expected, build/dokka/htmlMultiModule/childProjectB two contains 2 documented classes

   

8. Delete ./parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass2.kt

9. Re-run ./gradlew dokkaHtmlMultiModule

10. ⚠️ build/dokka/htmlMultiModule/childProjectB still contains documentation for ChildProjectBClass2, even though it was deleted

11. Delete the entire build/dokka/htmlMultiModule directory

12. Re-run ./gradlew dokkaHtmlMultiModule

13. Again, there is still a file for ChildProjectBClass2, even though I deleted the entire build directory.

Dokka configuration

https://github.com/Kotlin/dokka/tree/master/examples/gradle/dokka-multimodule-example

Installation

• Operating system: n/a
• Build tool: Gradle 7.6
• Dokka version: 1.8.10

Additional context

This problem also affects Dokkatoo. I have created a Gradle-based workaround, but this problem will probably also affect the CLI and Maven.

[IgnatBeresnev]

Delete ./parentProject/childProjectB/src/main/kotlin/demo/ChildProjectBClass2.kt

Re-run ./gradlew dokkaHtmlMultiModule

warning build/dokka/htmlMultiModule/childProjectB still contains documentation for ChildProjectBClass2, even though it was deleted

I'm not actually sure Dokka (the generator) should be expected to delete "deleted" files in this particular case. As I see it, Dokka (the generator) is very simple - you feed it the classpath for analysis, and it outputs the documentation for it. It doesn't actually know whether a class was deleted or not in-between runs. Shouldn't that be responsibility of the runner/build tooling?

DokkaGenerator could just delete everything from the output directories before writing into them, but wouldn't that lead to a greater amount of cache and other user problems? Like if Dokka deletes all files in the output directory and re-generates them even if nothing changed?

Come to think of it, in this case the definition of "deleted" would be "I know nothing about this output file", so from Dokka's perspective any output files it's not aware of are "deleted" and thus should be removed, so it would delete all files except for the new ones, effectively purging the output directory before writing into it...

Could the issue be narrowed down to "DokkaGenerator should delete all files from the output directory before writing into them"?

Delete the entire build/dokka/htmlMultiModule directory

Re-run ./gradlew dokkaHtmlMultiModule

Again, there is still a file for ChildProjectBClass2, even though I deleted the entire build directory.

What's happening here is most likely the htmlPartial directory is still present in childProjectB, with the new class. So when you run dokkaHtmlMultiModule - it just copies the htmlPartial directory downstream. If you delete the htmlPartial directory of childProjectB, run Dokka and you still see the new class - I'd be amazed