https://kotlinlang.org logo
Join Slack
Powered by
Hey everyone :wave:, Anyone has any idea what is c...
# dokka
s
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
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
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
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
Okay perfect, thank you for testing it out and reporting back! Much appreciated
i
Does arrow host Dokka docs anywhere? can't seem to find any link
s
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
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
Add_an_external_link_to_serialization.patch
s
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
links to kotlin stdlib, java core and I think some android types are enabled by default, yeah
👌 1
s
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
Hmm, not sure. 
kotlinx.coroutines
utilizes knit a lot like that, I wonder if there's a similar case to yours
s
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
yeah, I guess then it might be for GitHub only, not tested for dokka 😞
s
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
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
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
Open in Slack
PreviousNext
Powered by