[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 [K2] Support KMP projects #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

• [K2] Migrate to new Standalone Analysis API #3114
• [K2] Typealias to functional type with reciever leads to IndexOutOfBoundsException #3392
• [K2] Javadoc links for references on inherited properties is not rendered #3350
• [K2] Enum entry methods are not rendered #3336
• [K2] Support kotlin-as-java and javadoc plugins #3135
• [K2] Members of enum entry are not displayed #3129
• [K2] Support [this] link for extensions #3207
• [K2] KDoc links for extensions are unresolved #3234
• [K2] Unresolved KDoc links to typealias #3335
• [K2] Reference to class is not rendered under @constructor #3352
• [K2] List reference leads to the stdlib collections package #3375
• [K2] Methods implemented by delegation miss the override keyword and KDoc #3384
• [K2] Unstable documentable order #3250
• [K2] Unresolved java annotation methods in KDoc #3316
• [K2] Non-existent parameter from KDoc doesn't appear on the implicit primary constructor page #3348
• [K2] Reference to a class with quoted name is not resolved #3356
• [K2] Java nested classed are shown in inheritors #3363
• [K2] Generic inherited members have own dedicated pages #3196
• [K2] Incorrect modifier for property from getter/setter #3339
• [K2] Incorrect link for methods with parameters in Java stdlib #3355
• [K2] Missed source link for generated getter/setter in kotlin-as-java output #3367
• [K2] Generated getter for property in kotlin-as-java doesn't inherit kdoc description #3369
• [K2] Inconsistent member representation for Java/Kotlin files #3338

Upstream issues

• KT-60884 - Analysis API: Improve standalone mode project model creation.
• KT-62695 - K2 IDE: Unresolved extension functions in KDoc
• 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
• KT-62880 - K2 IDE: Unresolved java annotation methods in KDoc
• KT-62405 - Analysis API: Symbols SUBSTITUTION_OVERRIDE have no overridden symbols
• KT-64067 - Analysis API: Member scope has an inherited nested class from Java
• 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: #3328

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