Intellij IDE doesn't support dokka javadoc format

[aleksander-stanczak]

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?

[yole]

What exactly doesn't work? There is no support for showing documentation from external javadoc for Kotlin declarations, it's only supported for Java.

[deje07]

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.

[yole]

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.

[deje07]

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.

[Alefas]

@gszecsi, unfortunately, this task is out of our priority right now. If you are ready to invest some time into implementing this, we can help by implementing needed APIs (if it's not yet implemented) or show you existing APIs, otherwise we have to ask you to be patient and wait.

[deje07]

I'm interested in dealing with this issue however the amount of time that can be invested by me is unknown. First I'd like to know a bit more about the amount of work to be done, so could you please provide more information about that API you mentioned? I suppose it is available in the Community Edition but there might be some other source of information as well.

[Alefas]

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.

[sebastienrouif]

@gszecsi I'm facing the same issue/request. Did you make some progress on this?

[LedanDark]

@yole @Alefas Has there been any updates on this issue, or is the only current way to provide full source?

[semoro]

@LedanDark You can provide stripped sources (Only with public methods without bodies but with doc-comments)

[budius]

@semoro can u supply a code snippet for that? Simply adding the snippet below generates complete source codes.

	task sourcesJar(type: Jar) {
		classifier = 'sources'
		duplicatesStrategy = "exclude"
		from android.sourceSets.main.java.source
	}

[semoro]

@budius This requires a bit of work, which can't be done simple right now

[danielwilson1702]

:( 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?

[deje07]

:( 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?

It is possible to create documentation, even javadoc-looking html format is available, and you can read them using any browser. The problem is that IDEA cannot use any externally-supplied documentation for the Quick Documentation popup and such features.

Unfortunately I lack the time to look into this issue and try to implement a documentation provider for Kotlin :( Maybe next spring, unless someone solves this issue till then.

[yunikkk]

Suppose nothing has changed yet and there is no way to share javadocs generated with dokka for private library?

[kamildoleglo]

@yunikkk I don't quite understand what you mean by share javadocs generated with dokka for private library. You can generate the documentation and then host it on some server or just compress and share it

[yunikkk]

@yunikkk I don't quite understand what you mean by share javadocs generated with dokka for private library. You can generate the documentation and then host it on some server or just compress and share it

You're absolutely right, I can generate the lib-javadocs.jar. At the same time IDEA won't show the docs unless lib-sources.jar is also available. This is what the issue itself is about and I've just asked if there are any updates.

[Kordyjan]

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.

[Kordyjan]

I allowed myself to change the title to better reflect current scope of this issue.

[gzoritchak]

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.

It is an important use case:

• delivering closed source libraries with documentation of public/protected elements (through a dedicated artifact),
• being able to access to the documentation from Intellij Idea

It's both a dokka/Intellij feature.

[Legion2]

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.

[Chozzle]

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.

@Legion2 Can I ask how you publish only certain files as source? I can't find the api to do that. Or did you just strip the jar after it was generated?

[Chozzle]

Also, publishing only public api sources works if minification is turned off. As soon as I turn on r8 minification, the IDE fails to load documentation from sources. I have no idea how to debug this.

[IgnatBeresnev]

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.

[Legion2]

@Chozzle here is the gradle task I use, but I'm not sure if it still works

val sdkApiSourceJar by tasks.registering(Jar::class) {
    from(kotlin.sourceSets.getByName("androidMain").kotlin.srcDirs)
    archiveClassifier.set("sources")

    include("org/example/**")
}

[Chozzle]

@Legion2 Thanks I managed to get it working with something similar. The final boss is to get it working while proguard is turned on. You didn't happen to? See here https://stackoverflow.com/questions/74637696/published-sources-in-maven-local-repository-not-visible-in-android-studio-ide-if

[Legion2]

We only use consumerProguardFiles to add proguard rules, which are applied in the library user project if they have enabled proguard. But we don't minify published artifacts.

[yakovliev-hover]

@Legion2 Thanks I managed to get it working with something similar. The final boss is to get it working while proguard is turned on. You didn't happen to? See here https://stackoverflow.com/questions/74637696/published-sources-in-maven-local-repository-not-visible-in-android-studio-ide-if

@Chozzle can you please explain, in what manner it is working for you and what exactly you have managed to achieve? I am a bit confused, as this task is still Open, so I assume that the issue is not solved yet. Have you found workaround that allows to show some documentation on the level of IDE?