Today in the key note kdm/kdoc.jar was mentioned/a...

# dokka

[Lukas K-G]

Today in the key note kdm/kdoc.jar was mentioned/announced. Assuming that this will be achieved with dokka, is there any documentation around this already somewhere?

[Lukas K-G]

https://www.youtube.com/live/MmwBJbzWbV0?t=1077&is=fKALY3oRnJsyMUv-

[Oleg Yukhnevich]

Sure, see https://kotlinlang.slack.com/archives/C0F4UNJET/p1778576023732039

[Eugen Martynov]

I need to read and keep it interesting, as the jar format is used for documentation? Most probably to be seamless with the JVM world.

[Oleg Yukhnevich]

kdoc.jar is more about the concept itself - an artifact published to Maven Central, in a similar way we have javadoc.jar there.
In addition, as you might have already noticed, Kotlin uses .jar files not only to store JVM bytecode. In the end, it's just a zip file.

[Eugen Martynov]

Yeah, why not zip if it is zip by the end.

[Oleg Yukhnevich]

Why javadoc.jar is not a javadoc.zip? 🙂
As for kdoc.jar, it's not set in stone in any case, but it's much easier to describe in relation to the JVM ecosystem, at least.
Still, as Kotlin "extends" the Java world, we sometimes need to make small sacrifices to be compatible with it. As shown in the screenshot above, a jar is used because Maven Central requires the main artifact to be a jar.

[Eugen Martynov]

Sorry, was not clear with the original question - I hoped that someone knows also why javadoc is jar. And thank you for confirming that it is because of Java relationship.

[Oleg Yukhnevich]

As per JAR File Specification:

JAR file is a file format based on the popular ZIP file format and is used for aggregating many files into one. A JAR file is essentially a zip file that contains an optional META-INF directory. A JAR file can be created by the command-line jar tool, or by using the java.util.jar API in the Java platform. There is no restriction on the name of a JAR file, it can be any legal file name on a particular platform.

So, it's like a standard for storing anything related to Java.
And when the first build systems and artifact registries were born, and the need to publish sources or javadoc emerged, the easiest choice was to use a jar for everything. It both automatically says that it's related to Java and provides a META-INF directory for metadata.
This is mostly my understanding, though.

[Eugen Martynov]

Thanks!

[hfhbd]

Will it also be possible to wire the kdoc.jar (the documentation) inside AA/compiler api when declaring the dependencies via KGP? In the end, as a compiler/AA plugin author, I just want to access the documentation from 3rd party libraries without fetching the kdoc manually

[Oleg Yukhnevich]

I've tried to touch this topic in one of the comments on the KEEP itself, related to AA - https://github.com/Kotlin/KEEP/discussions/484#discussioncomment-17060790 (and maybe in some other long comment)
TL;DR:
• With AA, it will be technically possible, though, currently there is no "AA plugins", and so every consumer always collects everything by themselves from KGP (sources, classpath, kdoc.kar in the future). Be it KSP, Dokka, Swift Export, Amper Kotlin Toolchain, or any other consumer. I don't know if there is a YT issue about having some kind of AA (and so read-only/analysis) plugins so that we can automatically get this information from KGP into AA sessions, but it could be really nice! Feel free to create one - I was thinking about doing this myself, but all of the use-cases I see are mostly internal (mentioned above), and so it's not clear to me how big a demand there is.
• With the compiler, the situation is a bit harder, as there is currently no machinery in the compiler (FIR) to work with documentation on declarations. Probably, the first step in this direction is KT-83700 (Move KDoc resolution from the Analysis API to the compiler frontend), but it's not something we are aiming at first.