Dokka: Plugin stripping not public symbols and function bodies from close-sourced libraries.

[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.