Migrate Dokka's analysis to the K2 compiler API #2888
Assignees
Labels
enhancement
An issue for a feature or an overall improvement
epic
A large body of work that is broken down into smaller issues
topic: K2
Issues / PRs that are related to the K2 migration. See #2888
Milestone
Comments
IgnatBeresnev
added
the
enhancement
Merged
IgnatBeresnev
added
the
epic
This was referenced Aug 24, 2023
IgnatBeresnev
changed the title
|
The K2 analysis prototype has been imlpemented in #3094 🎉 Currently, the following projects are supported:
However, we are unable to proceed further and stabilize Kotlin/JVM projects until K2 introduces some additional API. A separate issue has been created to keep track of this: This issue's description has been updated, and additional issues have been created to reflect the current status. |
IgnatBeresnev
added
the
topic: K2
Current statusThe team has made significant progress in stabilizing the K2 analysis implementation. Many of our efforts also help find and fix bugs in the K2 IDE plugin, since we share a lot of the underlying analysis logic (same low-level API). Since the last update, we've been unblocked with stabilizing Kotlin/JVM projects, have fixed the known major issues, and have completed the first iteration of testing Dokka manually on a variety of user projects (#3328). The subtasks have been updated accordingly, they now include the newly discovered bugs and other issues. We will proceed with stabilizing Kotlin/JVM projects in the near future, aiming to enable K2 for them by default in Dokka 2.0.0, possibly making it available for public testing before the release. Once Kotlin/JVM projects are stable, we'll switch to KMP projects, aiming to enable K2 for them by default in Dokka 2.1.0, but we'll do it sooner if possible (Dokka depends a lot on the upstream API issues). The API that Dokka uses for K2 analysis is not yet stable, so we encounter various issues and bugs, which we report to Kotlin's YouTrack. Analysis API issues that affect Dokka in one way or another are marked with the kt-analysis-dokka tag in YouTrack. I'll leave a list of issues below for future reference. Bugs affecting Kotlin/JVM projects:
KMP-specific issues: API stabilization issues:
Noticeable differences in Dokka's behaviour that likely come from the upstream Analysis API, but it's undecided if they are bugs, so no YouTrack tickets yet: |
svc-squareup-copybara
pushed a commit
to cashapp/misk
that referenced
this issue
Dec 17, 2024
| Package | Type | Package file | Manager | Update | Change | |---|---|---|---|---|---| | [org.jetbrains.dokka:dokka-gradle-plugin](https://github.com/Kotlin/dokka) | dependencies | misk/gradle/libs.versions.toml | gradle | major | `1.9.20` -> `2.0.0` | --- ### Release Notes <details> <summary>Kotlin/dokka (org.jetbrains.dokka:dokka-gradle-plugin)</summary> ### [`v2.0.0`](https://github.com/Kotlin/dokka/releases/tag/v2.0.0): 2.0.0 Dokka 2.0.0 focuses on simplifying configuration and preparing for support of future Kotlin language features. Key highlights include: - **Dokka Gradle Plugin v2**: revamped Gradle plugin based on [Dokkatoo](https://github.com/adamko-dev/dokkatoo). - **Experimental K2 Analysis**: support for K2 compiler frontend. - **HTML Improvements**: better accessibility and easier customization. More details about each of the changes below. See [Dokka 2.0.0](https://github.com/Kotlin/dokka/milestone/31?closed=1) milestone for the list of all changes. #### Dokka's Gradle plugin v2 based on [Dokkatoo](https://github.com/adamko-dev/dokkatoo) > Please check the [migration guide](https://kotl.in/dokka-gradle-migration) for the update procedure and give feedback! Dokka 2.0.0 introduces significant improvements to Dokka Gradle plugin, aligning more closely with Gradle best practices: - Adopts Gradle types, which leads to better performance. - Uses an intuitive top-level DSL configuration instead of a low-level task-based setup, which simplifies the build scripts and their readability. - Takes a more declarative approach to documentation aggregation, which makes multi-project documentation easier to manage. - Uses a type-safe plugin configuration, which improves the reliability and maintainability of your build scripts. - Fully supports Gradle [configuration cache](https://docs.gradle.org/current/userguide/configuration_cache.html) and [build cache](https://docs.gradle.org/current/userguide/build_cache.html), which improves performance and simplifies build work. ##### Changes from Dokka 2.0.0-Beta - Forward Dokka Generator messages to Gradle logger (Kotlin/dokka#3833) - Add deprecated property to help migrate from JSON Dokka plugin configuration (Kotlin/dokka#3877) - Rename `dokkaPublicationDirectory` to `basePublicationsDirectory` (Kotlin/dokka#3876) - Rename `dokkaModuleDirectory`, and mark as internal (Kotlin/dokka#3880) - Update and add KDoc for DGPv2 (Kotlin/dokka#3842) - Remove DokkaPluginParametersBuilder (Kotlin/dokka#3872) - Increase default max heap of Worker to 2G (Kotlin/dokka#3913) - Remove the dependency of `dokkaGenerate` on `dokkaGenerateModule*` (Kotlin/dokka#3920) - KT-71784 Fix classpath for KMP shared source sets (Kotlin/dokka#3942) - Fix DGP/KMP integration, so Dokka can 'see' code from shared source sets in target source sets (Kotlin/dokka#3814) #### Dokka's K2 analysis Dokka 2.0.0 introduces **K2 analysis**, which is currently in an experimental stage. Dokka's K2 analysis leverages Kotlin's K2 compiler frontend for analysing code and uses the same shared Analysis API, which is used in [IntelliJ IDEA’s K2 mode](https://blog.jetbrains.com/idea/2024/11/k2-mode-becomes-stable/). The output with K2 analysis should mostly match that of K1 analysis, but there may be minor differences. We are actively working towards stabilizing K2 analysis and are planning to enable K2 analysis by default in future. To opt in to Dokka's K2 analysis, add the following flag to your project's `gradle.properties` file: ```properties org.jetbrains.dokka.experimental.tryK2=true ``` ##### Known limitations: - Intersecting source roots ([#​3701](Kotlin/dokka#3701)) and intersecting sample roots ([#​3373](Kotlin/dokka#3373)) may cause issues. - Kotlin/JS libraries compiled with the [legacy Kotlin/JS compiler](https://kotlinlang.org/docs/js-ir-compiler.html) are not supported ([#​3751](Kotlin/dokka#3751)). We would greatly value your feedback if you encounter any of these limitations. ##### Potential differences between the outputs of K1 and K2: While the output of K2 analysis aims to align with K1, there are some differences to be aware of: - Java synthetic properties: rendering may vary ([details](Kotlin/dokka#2888 (comment))). - KDoc links: resolution and rendering differences ([details](Kotlin/dokka#2888 (comment))). - Inconsistent documentable rendering order ([#​3590](Kotlin/dokka#3590)). - Enum entries: anonymous and overridden methods are no longer rendered ([#​3129](Kotlin/dokka#3129)). - Other differences may arise due to variations in type inference between K1 and K2. #### HTML format Dokka 2.0.0 introduces some changes to HTML output. We updated the structure of some elements and classes, particularly in the navigation and sidebar, to improve accessibility and simplify maintenance. These changes only affect you if you previously [customized](https://kotlinlang.org/docs/dokka-html.html#customization) Dokka styles. - We removed redundant wrappers like `navigation--inner` and `navigation-title`. - We reworked blocks such as `versions-dropdown` to make them more accessible. - We renamed classes like `navigation-controls--homepage` to improve consistency. For example, it’s now called `navigation-controls--btn_homepage`. For more information, see the [pull request](https://github.com/Kotlin/dokka/pull/3917/files). The easiest way to update your current templates is to adjust the [new templates](https://github.com/Kotlin/dokka/tree/master/dokka-subprojects/plugin-base/src/main/resources/dokka/templates) to your needs. #### Bugfixes - Fix merging expect-actual declarations (Kotlin/dokka#3875) #### Other changes - Update the external link URL for stdlib (Kotlin/dokka#3938) #### Feedback We would appreciate your feedback! - Please report any feedback or problems https://kotl.in/dokka-issues - Chat with the community visit #dokka in https://kotlinlang.slack.com/ (To sign up visit https://kotl.in/slack) **Full Changelog**: Kotlin/dokka@v1.9.20...v2.0.0 </details> --- ### Configuration 📅 **Schedule**: Branch creation - "after 6pm every weekday,before 2am every weekday" in timezone Australia/Melbourne, Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate). GitOrigin-RevId: 585ec9cbb39b481920aae89e0c6884b1e682110a
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Background
Dokka depends on the Kotlin compiler to analyze source code and KDoc comments.
Kotlin's K2 compiler has been in the works for some time, and it is going stable in Kotlin 2.0.
That means that the K1 compiler API that Dokka uses will be phased out over time, and Dokka should migrate its analysis to use the new K2 compiler API.
Steps
There are 4 major steps to make this migration happen:
1. Extract K1 analysis from
dokka-base(✅)The current K1 analysis is deeply ingrained in
dokka-base, with internal compiler types being exposed in public API and used by downstream plugins. This makes the migration to K2 very painful both for maintainers and for downstream users.K1 analysis should be extracted from
dokka-base, and a commonanalysis-apiabstraction should be introduced, making it possible for K1 and K2 implementations to coexist at the same time and be used interchangeably.Update: This step has been done, see #3099 for more details.
2. Implement a prototype to identify blockers (✅)
K2 already provides some semi-stable API that Dokka can use. We should migrate as much of the analysis as possible to identify the missing API and other blocking issues that would need to be addressed by the compiler team.
3. Stabilize JVM-only projects (In Progress)
Kotlin/JVM projects should be easier to support and debug on, so this is the first step in migrating users to the new K2 analysis.
Once generating documentation for Kotlin/JVM projects is stable enough, we will enable K2 analysis by default for such projects.
4. Stabilize KMP projects (semi-blocked)
Once Kotlin/JVM projects are stabilized, the only thing left will be to support Kotlin Multiplatform projects. This is a separate step as it will likely require more time to test it and support less trivial parts of KMP, such as native libraries.
While some KMP projects do already work, there are many corner cases and issues that need to be fixed, both on Dokka's side and in Analysis API.
Blocking issues:
Technical debt
A collection of issues and TODOs that are not necessarily part of any particular step, but that need to be addressed either during the migration or after it:
Related issues
Have a look at the issues marked with the topic: K2 tag to see what's been done and what still needs to be addressed in relation to this issue.
The text was updated successfully, but these errors were encountered: