Generated source folders are not included in documentation

[JakeWharton]

Describe the bug
Tasks which generate public API source do not have those sources included in generated documentation.

Expected behaviour
Documentation includes generated source content.

Screenshots
See below

To Reproduce
Given dokka-bug.zip:

1. Build project.

   $ ./gradlew assemble`
   

2. Observe generated sources included in .jar.

   $ unzip -l build/libs/dokka-bug-jvm.jar
   Archive:  build/libs/dokka-bug-jvm.jar
     Length      Date    Time    Name
   ---------  ---------- -----   ----
           0  02-01-1980 00:00   META-INF/
          25  02-01-1980 00:00   META-INF/MANIFEST.MF
          24  02-01-1980 00:00   META-INF/dokka-bug.kotlin_module
           0  02-01-1980 00:00   com/
           0  02-01-1980 00:00   com/example/
         484  02-01-1980 00:00   com/example/GeneratedApi.class
         475  02-01-1980 00:00   com/example/StaticApi.class
   ---------                     -------
        1008                     7 files
   

3. Build Dokka HTML.

   $ ./gradlew dokkaHtml
   

4. Observe generated sources not included in output.

   $ open build/dokka/html/index.html
   

   

Installation

• Operating system: macOS/Windows/Linux
• Build tool: Gradle 7.6
• Dokka version: 1.7.20

[IgnatBeresnev]

Thanks for the reproducer!

Seeing how the original issue is tagged with "PR welcome", I thought I'd return the favor by sending one :)

For some reason, generated sources are suppressed by Dokka by default - not sure what the reasoning behind the default value is.

However, there's an option that allows you to control it. For the reproducer project:

dokkaHtml {
  dokkaSourceSets {
    configureEach {
      suppressGeneratedFiles.set(false)
    }
  }
}

Perhaps, it should be automatically set to false (i.e document generated sources) in certain scenarios, as we sometimes have similar questions (such as #2821) that come from Android/KMP projects.

Like if certain libraries/plugins are used or code-generating tasks are present, given we can identify them somehow. Emitting a warning ("you have undocumented generated code") could be an option, but it might be annoying to see each time. Do you have any thoughts on that?

[IgnatBeresnev]

I'll close the issue as the problem was fixed downstream, but any thoughts on my comment above would be appreciated