[K2] Stabilize pure Kotlin/JVM and mixed Kotlin/Java projects

[IgnatBeresnev]

This issue is part of a larger issue: Migrate Dokka's analysis to K2 compiler (#2888).

Goal

Dokka should be able to generate documentation for any pure Kotlin/JVM project, or any project that uses a mix of Kotlin and Java together.

That means, it has to work with:

• All JVM versions officially supported by Kotlin. Running on Java 8, 11 and 17 should produce the same result.
• Projects that use pure Java and/or JVM-only Kotlin libraries (KMP libraries fall outside of the scope, they should be addressed in #3137). All user-visible types must be resolved correctly, including external documentation links.
• Projects that only use Kotlin's standard library and/or Java SE API directly (declarations from java.lang, java.util and similar packages).
• Dokka's JVM-only Javadoc format.

Once done, we should be able to turn on the K2 analysis by default for all JVM-only user projects.

Due date

The K2 analysis should be used by default in all JVM-only user projects in Dokka 2.0.0, with the ability to fall back to K1.

If there are unresolved issues or bugs by that time, at the very least it should be available for early testing (i.e toggleable via a flag).

Sub-tasks

• [x] https://github.com/Kotlin/dokka/issues/3114
• [x] https://github.com/Kotlin/dokka/issues/3392
• [x] https://github.com/Kotlin/dokka/issues/3350
• [x] https://github.com/Kotlin/dokka/issues/3336
• [x] https://github.com/Kotlin/dokka/issues/3135
• [x] https://github.com/Kotlin/dokka/issues/3129
• [x] https://github.com/Kotlin/dokka/issues/3207
• [x] https://github.com/Kotlin/dokka/issues/3234
• [x] https://github.com/Kotlin/dokka/issues/3335
• [x] https://github.com/Kotlin/dokka/issues/3352
• [x] https://github.com/Kotlin/dokka/issues/3375
• [x] https://github.com/Kotlin/dokka/issues/3384
• [x] https://github.com/Kotlin/dokka/issues/3250
• [x] https://github.com/Kotlin/dokka/issues/3316
• [ ] https://github.com/Kotlin/dokka/issues/3348
• [ ] https://github.com/Kotlin/dokka/issues/3356
• [x] https://github.com/Kotlin/dokka/issues/3363
• [x] https://github.com/Kotlin/dokka/issues/3196
• [ ] https://github.com/Kotlin/dokka/issues/3339
• [x] https://github.com/Kotlin/dokka/issues/3355
• [ ] https://github.com/Kotlin/dokka/issues/3367
• [ ] https://github.com/Kotlin/dokka/issues/3369
• [ ] https://github.com/Kotlin/dokka/issues/3338

Upstream issues

• [x] KT-60884 - Analysis API: Improve standalone mode project model creation.
• [x] KT-62695 - K2 IDE: Unresolved extension functions in KDoc
• [x] KT-64051 - K2 IDE: Analysis API: Unresolved links to typealias in KDoc
• [ ] (we have a local workaround) KT-64190 - K2 IDE: Analysis API: KDoc link leads to a function instead of interface
• [x] KT-62880 - K2 IDE: Unresolved java annotation methods in KDoc
• [x] KT-62405 - Analysis API: Symbols SUBSTITUTION_OVERRIDE have no overridden symbols
• [x] KT-64067 - Analysis API: Member scope has an inherited nested class from Java
• [x] KT-64833 - Analysis API: Members implemented by delegation have no overridden symbols

[IgnatBeresnev]

Current status

We are unable to properly configure K2 analysis for JVM projects due to missing API in K2.

Blocking issue: KT-60884 - Analysis API: Improve standalone mode project model creation.

Blocking issue's due date: around the release of Kotlin 1.9.20. It's unlikely that the fix we need will be part of Kotlin 1.9.20 itself, but it should be out at around that time, so we'll likely have to depend on a -dev artifact of either 1.9.20 (if it's backported into a custom branch) or of whatever the next version is going to be.

Notes: it might be possible to fix this issue on Dokka's side without the need to wait for KT-60884, but the solution is not guaranteed to be trivial or stable, so it's preferable to avoid it and wait for the proper API to be added.

[IgnatBeresnev]

Current status

The blocking Analysis API issue was addressed, and we were able to proceed with stabilizing Kotlin/JVM projects.

Having fixed the major bugs we were aware of, we prepared the testing infrastructure and started manually testing Dokka on a variety of user projects, a considerable number of which were Kotlin/JVM projects. More details and results here: https://github.com/Kotlin/dokka/issues/3328

Based on the testing results and findings, I've updated the subtasks of this issue with the new issues.

[vmishenev]

Dokka 2.1.0 has been released with K2 analysis enabled by default. It fully supports Kotlin/JVM and KMP projects. There are no known blockers that would force users to fall back to K1. The output with K2 analysis should mostly match that of K1 analysis, but there may be minor differences.