dokka: Intellij IDE doesn't support dokka javadoc format
I have following configuration in build.gradle file:
buildscript {
ext.dokka_version='0.9.15'
repositories {
jcenter()
}
dependencies {
classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version"
}
}
apply plugin: 'org.jetbrains.dokka'
task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {
outputFormat = 'javadoc'
outputDirectory = "$buildDir/dokkaJavadoc"
}
task packageJavadoc(type: Jar, dependsOn: 'dokkaJavadoc') {
from "$buildDir/dokkaJavadoc"
classifier = 'javadoc'
}
artifacts {
archives packageJavadoc
}
This generates properly looking javadoc jar (“${moduleName}-javadoc.jar”). However when imported with Intellij Idea, while it is detected as javdoc jar, IDE support doesn’t work. Is it format incompatibility with javadoc produced by dokka or just IDE bug?
About this issue
- Original URL
- State: open
- Created 7 years ago
- Reactions: 15
- Comments: 28 (9 by maintainers)
The benefit would be that even non-open-source projects could allow subcontractors or employees to use their libraries written in Kotlin, and still be able to use the Quick Documentation feature of IDEA/Android Studio. Kotlin is a great language and environment to overcome Java’s issues, so I think it is a good point of view that more and more people will consider using it against Java. You are saying that “vast majority of Kotlin code available”, but here both the terms “vast majority” and “available” are quite subjective.
I personally (and our subcontractors also) really would like if IDEA/Android Studio supported showing Kotlin external documentation.
IntelliJ IDEA does not support any external documentation for Kotlin sources. Given that the vast majority of Kotlin code available today is open-source, it’s unclear what benefit exactly the support for external docs would bring.
It is an important use case:
It’s both a dokka/Intellij feature.
As people keep coming back to this issue, let me comment on its current status and the general problem.
IDEs (and other tools) are made to work with Java’s Javadoc output, the original one developed for the Java ecosystem. So tools expect certain page structure, HTML tags and CSS classes to be present in order to extract information, and it can indeed be found in Java’s Javadoc HTML.
However, Dokka’s Javadoc format is not a direct implementation and is not 100% compatible at the moment. It is merely a lookalike which is generated based on templates. It tries to follow the same rules and visuals, but it’s not always right. That being said, integrations with tools that expect true Javadoc HTML are not guaranteed to work.
Dokka’s Javadoc format, as of 1.7.20, is also in Alpha, meaning it’s not polished, there are noticeable bugs and it is pretty much a PoC. Hopefully we will get to stabilizing it, thus improving various integrations, but there’s no such plans for the near future (<= 1.8.20) as we first want to stabilize Dokka’s own HTML format. What lies beyond 1.9 is a mystery, we’ll have to see 😃
However, it does not mean we won’t fix bugs in the Javadoc format until then - we will, but it has lower priority.
If you have the time to investigate and contribute fixes yourself (like done in #2033), it would be much appreciated, we’d be happy to guide you with the technical aspects.
This issue remains open as an umbrella issue, at least until all the major bugs are fixed.
You’re absolutely right, I can generate the
lib-javadocs.jar. At the same time IDEA won’t show the docs unlesslib-sources.jaris also available. This is what the issue itself is about and I’ve just asked if there are any updates.😦 Just came across this while researching kdoc, so right now it is impossible to publish my documentation from my private library, for consumers of that lib?
Suppose nothing has changed yet and there is no way to share javadocs generated with dokka for private library?
We only use
consumerProguardFilesto add proguard rules, which are applied in the library user project if they have enabled proguard. But we don’t minify published artifacts.Is there any progress on this issue? I was debugging why Android Studio isn’t showing the javadoc we published for our closed source library and discovered this issue.
As a workaround I know publish only the interfaces of the public api as source, so its documentation is shown in Android Studio.
I think this issue is more feature requests to IntelliJ than a bug in dokka. Nevertheless, I think dokka can help mitigate that. Plugin taking close sourced library and stripping all not-public symbols and removing all function bodies is trivial to create.
First of all you need is Kotlin plugin sources. Follow Readme, how to setup this. So what I would do to implement this. Take as example JavaDocumentationProvider, you can invoke quick do info in similar case and debug what’s going on. Then you need to implement similar things in KotlinQuickDocumentationProvider.
Regarding to APIs, it’s kind of metadata in dokka generated files to understand how to find doc by PsiElement and what to render, right now it’s not trivial, but you still can try in some way, it will be better than nothing in any case.
I think the next question would be that does IDEA/AndroidStudio support any kind of external documentation for Kotlin declarations? None of the provided Dokka output formats seems to be working.