As a regular user of the Dash offline API reference browser, I'm seeing a lot of uninstallable javadoc libraries (

httk4k

and

vavr-kotlin

for instance). Both have published javadoc jars that are empty apart from the MANIFEST, and both use Gradle to build. Also, the Kotlin stdlibs are missing from the available docsets. It feels that this is a systemic problem for Kotlin, and one that is a real negative for someone, like me, who likes to read the statement of how the code is intended to be used, rather than just relying on the current implementation (in source) Are there any plans to fix this?

http4k

doesn't have any documentation in the code and I'd guess that

vavr-kotlin

just adds an empty javadocs because maven-central requires it, but it doesn't really generate any documentation judging by the gradle-build-file

And Kotlin Stdlib with empty javadoc for

stdlib

and

stdlib-jdk8

?? COUGHS This feels like a systemic problem (with Dokka? Dokka + Gradle?)

It’s possible to publish javadoc with Dokka

it’s no problem at all to generate javadocs for stdlib, but why? what is the scenario in which you would use them?

@yole perhaps for offline browsing in tools like Dash or Zeal, as David said in the first message.

why is javadoc better for such tools than the current stdlib doc format?

Current docs have to be crawled from our site first, while javadoc jars are available to download from maven central. So perhaps the question is not about the format, but rather about the availability of docs.

Yes, plus that JavaDocs are supported by offline readers / browsers, which other formats are not

Dash supports any html as a source though https://kapeli.com/docsets#dashDocset

IDEs definitely help, but are not always available: When reviewing PRs for instance

last time I checked, Dash was perfectly capable of showing Kotlin reference documentation, which is not in Javadoc format

Downloading? Or just showing?

and if you need a reference on how to use the kotlin stdlib from kotlin code, then javadoc is a really poor way to represent this information, because it loses or distorts tons of Kotlin-specific details in the API

Also, I'm lazy - I have 50-60 lib docsets installed: I just want to search / click install / have dash autoupdate. My job is not managing doc references 😛

this is a legitimate wish, but generating javadocs for kotlin libraries is not a good way to fulfill it

So, there's a really good point about lossy translation: How best to agree / standardise a format that is supported by both artefactories and offline readers?

There's docset for Kotlin 1.3 here https://github.com/rojiani/kotlin-docset/releases

@David Hamilton sorry - we didn't realise that the http4k java doc jar was empty. Will look at fixing that (we use dokka to generate our API docs - although we don't generally do extensive API docs, what we do have is online at http4k.org/api)

Thanks @dave It also helps to have something to give to people new to our project (the HTTP4K docs are great - what there is! 😉 )

From KDoc comments in sources, exactly the same way as Doka/JavaDoc do

But are they packaged and installed separately? Or derived dynamically from the source code?

there are Jars with source code which downloaded by IDE and indexed, so you have full documentation, same way as you would have it with Javadoc

Ok, thanks. So there isn't a separate packaging for Dokka/KDoc API reference which we could publish and put to use elsewhere?

There are

That's what I also suspect - that by default Gradle isn't doing what many would expect to be the 'right' thing

If you generate javadoc from Maven for Kotlin project you will probably get exactly the same result

So, I see that Dash supports many formats (inc. non-Java and ScalaDoc). What format should I ask the developer to add support for?

I knew about Dash from this thread %) So don’t have advice for that. But as I understood, Dash can use any HTML as source of documentation, and this is exactly what Dokka generates by default

@David Hamilton I've just looked at fixing this in http4k. Unfortunately there is an open bug in Dokka which prevents the JavaDoc generation from working with Java 10+ (https://github.com/Kotlin/dokka/issues/294), so we're blocked on it, I've raised https://github.com/http4k/http4k/issues/196 to cover.

Many thanks for looking