Nice! Out of curiosity is it on purpose that the v...

# dokka

[mbonnin]

Nice! Out of curiosity is it on purpose that the versioning follows the Kotlin versioning? Like if I want to use Kotlin 1.8, do I need Dokka 1.8 or could it be that Dokka 1.7 works well? (except for the things above obviously)

[Javier]

I am not sure too, as I have used Dokka 1.7.20 in Kotlin 1.8.10 projects with... no issues? or maybe I was missing some of them 🤔

[mbonnin]

Same thing here, I've been using 1.7.20 fine.

[glureau]

I always presumed that if I was not using the latest language feature it should run fine. Could be interesting to have a write-up on this strategy.

[Ignat Beresnev]

Although I can't say for sure, I think it's both for historical reasons and because of the inner workings.

1. Dokka ships with the Kotlin compiler embedded, so it makes sense to align the versions and avoid compatibility matrixes. Right now it's also using the Kotlin IDE plugin artifacts for KDoc parsing, which also follow the Kotlin versioning.
2. There's a correlation between latest language features and the releases of Dokka, such that you can expect Dokka 1.8.10 to support shiny new things introduced in Kotlin 1.8.10, which also makes it a bit more transparent and helps avoid compatibility matrixes.
3. Dokka depends on KPG for autoconfiguration, and the versions are aligned here as well, which also makes it a bit easier to reason about, especially when it comes to new/deprecated API.
But Dokka should work fine with other versions of Kotlin in runtime, once you start the task as I believe it's bringing everything it needs. The only real problem I'm aware of is if the version of Dokka and the version of KGP in your project are not compatible - the version of KGP is the same for both your project and Dokka, no distinction here.

The approach with aligning versions has some disadvantages though:
1. Bugs in Kotlin can block our releases, like what happened with 1.8.0 - we couldn't release because of the memory leak in kotlin-reflect
2. It's not as easy for Dokka to publish very small bugfix releases. If Dokka has 1.8.10.1, but Kotlin doesn't - it's confusing. Some projects actually use the same version property for both Kotlin and Dokka
3. Kotlin is planning/developing way ahead compared to Dokka, so most of the time we're playing catch up. I believe there already exist builds for Kotlin 1.9.0 whereas we haven't even tried 1.8.20, and it'll most likely be a very painful update for us
All in all, not sure how to feel about it 🙂 Has its ups and downs

Would you prefer it if the versions were different?

[mbonnin]

Thanks for the insights 👍 No strong opinion here. I was mainly curious

[Javier]

IMO if there is not a strong dependency like compiler plugins, I would keep a separate version.

[mbonnin]

👍 I was actually writing this: I guess it could be argued that it's coupled to Gradle as well in some way (as well as other dependencies maybe) so it's impossible to track all of them and at some point, independent versionning would make sense

[Javier]

And I would expect that compiler plugins drop the Kotlin version suffix when the API becomes stable too

[mbonnin]

Ah yea, the "KSP situation" 🙂 👍

[mbonnin]

If Dokka ever switches to independent versioning (same thing happened for Androidx not so long ago), would be nice to have a big runtime check to fail early on incompatible KGP/Gradle versions

[Ignat Beresnev]

There were also talks of "embedding" Dokka into KGP itself. Like what we have with java and javadocs: there's no need to apply any external plugins - you just have the javadoc task and it generates documentation, as simple as that. In this scenario it'd also make sense to align the versions. But we've abandoned that idea for now

I believe AGP actually comes with Dokka built in, there should be a task for it, although I never checked...

[Javier]

That would be great, but if Dokka development is slower than Kotlin, would it not be a problem embedding Dokka in Kotlin?

[Ignat Beresnev]

You mean problematic for Kotlin or for Dokka?

[Javier]

for Kotlin, as Dokka will slow Kotlin development (or maybe embedding it solves the Dokka issues?)

[Ignat Beresnev]

If Dokka is included into the overall planning process of Kotlin, it should be OK

Kotlin has branching / feature freeze a few months before the actual release. Feature freeze for 1.8.20 was ~mid-January. So it would help identify blockers/problems much sooner, and Dokka shouldn't lag behind or slow Kotlin down

But Dokka's progress will be slowed down for sure. If there's a cool feature, right now we can plan and ship it in 1.8.20. If Dokka was embedded, we'd be able to ship it in 1.9 at best

[mbonnin]

I think I'd be ok with that if there's a good SNAPSHOT/EAP strategy that allows me to test the feature without waiting 6 months

[mbonnin]

(which is the case today with Kotlin, it's pretty cool to have those EAPs)

[Javier]

those features can't be plugins with a different release cadence and versioning?

[Ignat Beresnev]

those features can't be plugins with a different release cadence and versioning?

For huge format-specific features - maybe, yeah. But things like adding support for Kotlin/wasm projects can't be done in a separate plugin (at least not without major refactoring), it's core functionality

[Ignat Beresnev]

Just thought of another advantage of aligning the versions, I guess I'll keep posting them here in case this questions comes up again

It's crystal clear if you have an outdated version of Dokka as I'm sure everyone knows what the latest version of Kotlin is. With arbitrary version numbers like 1.4.2 it's not clear how old it is and whether it needs to be updated

[Joffrey]

There is also the question of decoupling the releases of Dokka from the releases of the Dokka Gradle plugin. Is there a technical reason for this coupling ? Dokka's slow cadence is slowing down the improvements on the Dokka Gradle plugin. There are plenty of pending critical contributions to the plugin from outside JetBrains, and it's a pity they have to wait for releases of Dokka itself.