Provide support to the Analysis API team in running and testing Dokka

[IgnatBeresnev]

Context

The Kotlin Analysis API team, who is responsible for developing the K2 Analysis API we're using, sometimes introduces breaking changes (be it in API or just bugs), which is fine as long as we can notice and address these problems in a timely manner.

The tests added in #3540 should help with catching unexpected problems, and they should also enable the Analysis API team to test their own builds against Dokka to see if something gets broken.

Some issues in Dokka's K2 analysis can also be fixed by the members of the Analysis API team, but they need to be able to build the project and know where to introduce changes and how to test them (they tried to build Dokka recently and couldn't due to #3517).

We should provide the necessary support to ease their life when working with Dokka, and this in turn will make our life easier.

Task

Send the Analysis API team instructions on:

• Some general context about the project, for instance how / where they can update the version of Analysis API, in which modules to make changes (analysis-kotlin-symbols), how to run K2 tests (symbolsTest?), whom to add as reviewers, etc.
• How to build / debug / publish Dokka locally.
• How to override the version of Analysis API when running locally from CLI
• How to run K2 tests in TeamCity with a custom version of Analysis API ([K2] Run unit tests against the latest kotlin-compiler builds #3540).

Some of these things are already described and just need to be gathered in a single message and sent to the Analysis API team. If some information is missing, it should be provided.

Additionally, it wouldn't hurt to ask them about the use cases they might have (in relation to working with Dokka) that are not covered by the instructions mentioned above.

[vmishenev]

Entry point: Where is the implementation of Dokka Analysis for K2?

The implementation of Dokka Analysis for K2 is in the :dokka-subprojects:analysis-kotlin-symbols subproject

The main entry point is DefaultSymbolToDocumentableTranslator (this is an extension for the extension point ), that is used by the Dokka core to build Documentable model by a source set.

Across running Dokka we keep StandaloneAnalysisAPISession and KtSourceModule instances into AnalysisContex. (See createAnalysisContext).
AnalysisContex is used in DefaultSymbolToDocumentableTranslator and other services that need an additional analysis.

How to run the Dokka tests with a custom version of Analysis API?

• To change the version of the Analysis API in Dokka, the property kotlin-compiler-k2 in gradle/libs.versions.toml should be changed to a needed version.
  Note: You may need to add a local repository in settings.gradle.kts
• The :symbolsTest Gradle task should be used to run Dokka unit tests with the only K2 analysis
• The :descriptorsTest task can be used to check the K1 analysis
• Dokka also has integration tests. To run them, :integrationTest with the property org.jetbrains.dokka.integration_test.useK2=true (or gradlew integrationTest -Porg.jetbrains.dokka.integration_test.useK2=true) should be called.
  They are run on TeamCity.
  Note: Currently, the integration tests do not check generated content very well. For testing analysis, It is better to run unit tests.

How to run the Dokka unit-tests with a custom version of Analysis API on TeamCity?

By default, we run unit tests on TeamCity against the latest Analysis API by a schedule here. It is possible to trigger a run with a custom version of Analysis API (the parameter Analysis API version should be used).

How to build/publish Dokka locally?

• You can use the :publishToMavenLocal task to publish Dokka locally. The published version is taken from gradle.properties.
• To build Dokka without running testing, Using the assemble task is recommended since the tests are time-consuming.

Please let me know if you have any questions.