Develop a documentation format for easier integration with tools, similar to javadoc.jar

[IgnatBeresnev]

Use case / Problem

This request is inspired primarily by #215. At the moment, if you want to import your KDoc documentation into IntelliJ IDEA (to be able to see quick docs without downloading source code), you have to go through generating a javadoc.jar with Java signatures, which, supposedly, get translated to Kotlin signatures at the time of displaying the docs in IntelliJ.

This abstraction sometimes leaks from both ends, which causes bugs/missing documentation/etc. Moreover, it places additional burden on Dokka to keep the Javadoc format up-to-date and with minimal integration bugs (that means, copying Java's Javadoc HTML as closely as possible), even though the format is still in Alpha.

At the moment, closed-source libraries that do not want to publish source code via sources.jar, but want to give the users the ability to view documentation from IntelliJ IDEA (or some other tool), suffer from the lack of proper integration the most.

To sum up: there's no native and proper way to integrate Kotlin API documentation with tooling. The only way is to generate an intermediate javadoc.jar with the Javadoc format and Java code signatures inside, but it leads to inaccuracies and bugs.

Possible solution

KDoc spec could describe a format dedicated specifically for integrations with tooling.

For instance, it could be a simple JSON file with something like the following:

{
  "package": "org.jetbrains.dokka",
  "containingClass": "public abstract interface class org/jetbrains/dokka/DokkaConfiguration : java/io/Serializable",
  "function": "public abstract fun getModuleName ()Ljava/lang/String",
  "documentation": {
    "description": "The main description of the declaration with a lot of text",
    "@return": "the name of the module",
    "@author": "Steve Jobs"
  }
}

Dokka (or some other community tool, or even the compiler) could then build these files from source code according to the spec.

IntelliJ IDEA (or some other tools that need this information) would then support parsing and processing of such files according to the spec.

Having it be part of the KDoc spec would add credibility and put less strain on Dokka, allowing generating and importing tools to be developed independently of each other.

[d-ambatenne]

Additional uses-case: reading the Kotlin libs documentation using offline readers such as Dash/Zeal/Velocity

[vmishenev]

Another possible use-case: #463 - providing external documentation in inheritors

[hfhbd]

Another use-case: I want to create an OpenAPI file and the schema should contain the documentation of the classes. I use KSP to resolve the schema for the given http endpoint, but KSP (or any compiler plugin) is only able to fetch the documentation of the current module (because the kdoc is dropped by the compiler), so resolving the doc from classes located in another module isn't possible right now.

As a workaround I apply ksp for each module and create my own documentation extractor using a custom ksp plugin.

If Dokka stores the documentation as machine format, I can drop my custom workaround.