https://kotlinlang.org logo
#dokka
Title
# dokka
s

simon.vergauwen

07/04/2022, 12:42 PM
Hey everyone 👋, Anyone has any idea what is causing all these
ERROR CLASS
in my generated HTML page? https://nomisrev.github.io/kotlinx-serialization-jsonpath/-kotlin-x%20-serialization%20-json-path/io.github.nomisrev/index.html It's referencing KotlinX Serialization types which is exposed through an
api
dependency 🤔
i

Ignat Beresnev

07/04/2022, 12:44 PM
Hi! Dokka is for some reason unable to inspect the types you're referencing. It mostly happens for klib and native formats Try updating to 1.7, it has better handling of klib libraries, might help
Hiya! Had some time to have a quick look, and indeed just updating to Dokka 1.7 solves the majority (if not all) problems 🙂
❤️ 1
🙏 1
s

simon.vergauwen

07/07/2022, 12:00 PM
Hey @Ignat Beresnev, thank you for looking into it 🙏 I looked into it but I got stuck upgrading to Kotlin 1.7.0 since there is still a breaking issue with Kotest 😞 Can I upgrade to Dokka 1.7.0 without bumping Kotlin to 1.7.0?
i

Ignat Beresnev

07/07/2022, 12:02 PM
I certainly didn't upgrade to Kotlin 1.7 in your repository and was able to generate documentation, so it should work 🙂 Dokka ships with its own compiler/intellij dependencies (so 1.7 uses 1.7), but it's mostly compatible with older/newer versions
s

simon.vergauwen

07/07/2022, 12:05 PM
Okay perfect, thank you for testing it out and reporting back! Much appreciated
i

Ignat Beresnev

07/07/2022, 12:12 PM
Does arrow host Dokka docs anywhere? can't seem to find any link
s

simon.vergauwen

07/07/2022, 12:22 PM
Yes, we do host Dokka documentation. Here is API docs that are generated by Dokka for Arrow. https://arrow-kt.io/docs/apidocs/arrow-fx-coroutines/arrow.fx.coroutines/
👌 1
A lot of our code is documented like this, https://github.com/arrow-kt/arrow/blob/1254f1b556c014af1ca23ea7a472776fb7bb58ed/ar[…]libs/core/arrow-core/src/commonMain/kotlin/arrow/core/Either.kt A pattern we were already used to from other languages like Scala and Rust. It's not always yielding the best results for us atm, also because we have quite some extension functions and we've not split it heavily into different packages.
We're also leveraging KotlinX Knit to verify the code in the snippets is compiles, and we hope to add tests to them as well soon as done in KotlinX Coroutines.
The Arrow docs generate Gfm instead of Html though
i

Ignat Beresnev

07/07/2022, 12:32 PM
JFYI since your new library is an extension of
kotlinx.serialization
, which also hosts Dokka docs, you can add an external link to it, so serialization classes will be resolved and should have correct links. I've attached a patch Also tried it out with arrow gfm docs to provide links for
Every
and
Optional
, but they're typealiases and Dokka doesn't generate separate pages for it, so the links are broken 😞 That'll have to be fixed
s

simon.vergauwen

07/07/2022, 12:41 PM
Oh awesome, thank you so much for that!
Didn't know about that. Should this also be added for Kotlin Std types? Or is that enabled by possible by default?
i

Ignat Beresnev

07/07/2022, 12:42 PM
links to kotlin stdlib, java core and I think some android types are enabled by default, yeah
👌 1
s

simon.vergauwen

07/07/2022, 2:41 PM
Do you know how I could fix the links used for Knit? They're working on the Github README, but they turned into broken links on the Dokka HTML page. https://nomisrev.github.io/kotlinx-serialization-jsonpath/
i

Ignat Beresnev

07/07/2022, 3:16 PM
Hmm, not sure.
kotlinx.coroutines
utilizes knit a lot like that, I wonder if there's a similar case to yours
s

simon.vergauwen

07/07/2022, 3:29 PM
Seems that section is not being turned into html?
The official Kotlin Docs website has a link of it, but it sends me back to the Github README. https://kotlinlang.org/docs/coroutines-guide.html#additional-references
There are some broken links here, https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-android/ But seems to be unrelated
i

Ignat Beresnev

07/07/2022, 3:32 PM
yeah, I guess then it might be for GitHub only, not tested for dokka 😞
s

simon.vergauwen

07/07/2022, 3:36 PM
The Dokka team is doing great work 🙏 Shall I create a ticket for this on the Dokka repo? I had a ticket here where we were already discussing it, https://github.com/Kotlin/kotlinx-knit/issues/31 The biggest issues are solved, which is great! Shall we leave that ticket open and update the description?
🦜 1
i

Ignat Beresnev

07/07/2022, 3:45 PM
Not entirely sure on which side and how it should be fixed. Dokka would have to know about the location to source files (I guess it can do that already) and the fact that this link leads to sources It would work if there was a full link instead of relative (so full
<http://github.com/yada/yada>
instead of
/src/test/yada
), maybe knit could (can?) do that instead?
s

simon.vergauwen

07/07/2022, 4:13 PM
If that would solve the issue that would work for me. This is automatically generated, and don't think you can influence it from a config but it would probably be the easiest and best fix.
I can try looking into that later
2 Views