It's weird, because it seems like a common thing t...

# dokka

[Michal Klimczak]

It's weird, because it seems like a common thing to do, but I swear, I can't find any info about this, maybe you guys can help. I want to attach javadocs to a closed source sdk. The goal is for the javadoc and names to be visible in IDE, but the method bodies should be stripped. I learned that I need to have sources.jar to show javadocs in IDE. But can I configure the sources jar to strip method bodies (ideally just leave public stuff)?

java {
    withSourcesJar()
    withJavadocJar()
}

[Karel Petránek]

You only need the javadoc jar to show javadoc in the ide. Sources always contain full source, it doesn’t make much sense to strip it as it is primarily meant to aid debugging and inspect implementations.

[Michal Klimczak]

I was hoping so, but it doesn't show without sources.jar and shows without any issues with sources.jar. And I've read in a few places that this might be by design

[Michal Klimczak]

I mean, the javadocs are generated just fine, I can open them in browser. But they will not be shown in Intellij with quick docs (F1)

[ephemient]

your Javadoc is uploaded to a maven repository with a javadoc classifier? I think IDEA may rely on that. if that's the case and it still doesn't work, I think this would be an IDE issue more than a Dokka issue

[Michal Klimczak]

not, it's not distributed by maven, I'm attaching it via flatDirs + implementation(":lib")
(tried via implementation(files("libs/lib.jar)" too)

[Karel Petránek]

That might be the issue, I’m not sure whether the IDE supports pulling javadoc from a flatdir. Does your javadoc jar have -javadoc.jar suffix?

[Michal Klimczak]

yes, to be precise, when I have

lib.jar
lib-javadoc.jar

Then it doesn't work.
But with

lib.jar
lib-javadoc.jar
lib-sources.jar

It does work. But contains full sources.

And I want something in between. I think I've seen libraries having stuff like this, though, that's why I'm asking about stripped sources.

fun method(params: Params){
   //undefined
}

[Karel Petránek]

I see, I think that’s an IDE issue as javadoc-only jars work fine when downloaded from a maven repository. You can try to install it to your maven local repository to see if it works from there.

[Ignat Beresnev]

Hi! Unfortunately, javadocs generated by Dokka don't work well with IDEs :(

It's not the primary format at the moment, but we do plan to improve it in the future after the stable release of our html format

https://github.com/Kotlin/dokka/issues/215

[ephemient]

regardless, I would recommend setting up a Maven repository, even a local one, over libs/*.jar, as that allows other dependency features

[Michal Klimczak]

@Ignat Beresnev and dokka is the only way to generate javadocs for kotlin code, right?

@ephemient this is a very specific use case - a self contained project that serves as a recruitment task for candidates and the closed source sdk is a mock-backend-api. So I was looking for something simple.

[Ignat Beresnev]

and dokka is the only way to generate javadocs for kotlin code, right?

I believe so

[Ignat Beresnev]

@ephemient this is a very specific use case - a self contained project that serves as a recruitment task for candidates and the closed source sdk is a mock-backend-api. So I was looking for something simple.

You can still document the SDK and build and host Dokka's HTML format docs, here's an example. You can use github pages or a webserver, you must be running nginx somewhere already 🙂 No body source code and no private functions will be visible

The search works well for finding classes/functions by signature. It's not as convenient as having documentation right in the IDE, but it still can be used as reference for not self explanatory API -- definitely better than nothing

[Michal Klimczak]

I'm torn betwen this and just writing a few sentences in the readme, because it's really a tiny API. Nevertheless, it's good to know what we can and what we can't do.

One more thing - you linked to a dokka issue tracker, but afaiu it's not a dokka issue, it's more of an intellij thing? Shouldn't we have an issue on JB tracker for that?

[Ignat Beresnev]

I'm torn betwen this and just writing a few sentences in the readme, because it's really a tiny API. Nevertheless, it's good to know what we can and what we can't do.

You could generate gfm format docs and embed it into the README file :)) However, gfm format is also at it's early stages and has some noticable bugs, so you may need to modify it. ./gradlew dokkaGfm . Here's an example: https://square.github.io/okhttp/4.x/okhttp/okhttp3/

but afaiu it's not a dokka issue, it's more of an intellij thing

I would say it's primarily Dokka's issue since it's responsible for generating javadoc pages. Rendering-wise, Intellij platform works well with Java's javadoc output, no questions there. So if Dokka were to generate "correct" javadocs (that is abiding by all rules and quirks of the format), it would work well.

But thing is, I don't think it's possible to generate 100% identical and idiomatic javadocs when not using java's javadoc task. Javadocs generated by Dokka look like Java's javadocs visually, some of the styles are the same, but everything under the hood is different, beginning with how sources are traversed and looked up and ending with the rendering (for Dokka it's template-based). Moreover, Kotlin has features that are difficult to display in Java's javadoc styling, since it was never intended to have this information - companion objects, extension functions, package-level functions, etc

Moreover, I don't think that Dokka should strive to generate such javadocs that could be read well by the IntelliJ Platform. Instead, a machine-readable output format (like xml) could be used instead to generate documentation, and then it could be imported into Intellij IDEA to have the same inside-editor quick docs as if imported from javadocs. This can be done already by custom dokka and intellij plugins, but we don't have the resources. Good idea for a pet / practice project 🙂