https://kotlinlang.org logo
Join Slack
Powered by
As a regular user of the Dash offline API referenc...
# announcements
d
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?
a
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
d
And Kotlin Stdlib with empty javadoc for 
stdlib
and 
stdlib-jdk8
?? COUGHS This feels like a systemic problem (with Dokka? Dokka + Gradle?)
g
It’s possible to publish javadoc with Dokka
Why do you need javadoc for stdlib?
or any other open-source library
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)
But javadoc generated from comments in source code, you can read this documentation in IDE, it will be just grabbed from source code, the same way as would javadoc generation work
I probably just don’t know your use case, I think javadoc should be published, just curious about use case
also generated documentation for stdlib available on Kotlin web site and description and samples part of source code
y
it’s no problem at all to generate javadocs for stdlib, but why? what is the scenario in which you would use them?
➕ 1
i
@yole perhaps for offline browsing in tools like Dash or Zeal, as David said in the first message.
y
why is javadoc better for such tools than the current stdlib doc format?
i
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.
d
Yes, plus that JavaDocs are supported by offline readers / browsers, which other formats are not
I would also say that tools like Dash add fast search capabilities
i
Dash supports any html as a source though https://kapeli.com/docsets#dashDocset
d
IDEs definitely help, but are not always available: When reviewing PRs for instance
y
last time I checked, Dash was perfectly capable of showing Kotlin reference documentation, which is not in Javadoc format
d
Downloading? Or just showing?
y
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
downloading
d
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 😛
y
this is a legitimate wish, but generating javadocs for kotlin libraries is not a good way to fulfill it
d
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?
Surely the publication types in Maven repos is extensible? (for, say, Dokka format?)
Hmmm, turns out I have 150 docsets & cheatsheets installed... more than I thought. The point being that a modern developer has to swap rapidly between many libraries and technologies, and the lower the cost of that 'context-switch' the more productive we are.
i
There's docset for Kotlin 1.3 here https://github.com/rojiani/kotlin-docset/releases
👍 1
d
@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)
d
Thanks @dave It also helps to have something to give to people new to our project (the HTTP4K docs are great - what there is! 😉 )
That's great @ilya.gorbunov - thank you.
There is a question that comes out of this thread: How are IDEs deriving their documentation information if it isn't from JavaDoc jars? 🤔
g
From KDoc comments in sources, exactly the same way as Doka/JavaDoc do
d
But are they packaged and installed separately? Or derived dynamically from the source code?
g
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
d
Ok, thanks. So there isn't a separate packaging for Dokka/KDoc API reference which we could publish and put to use elsewhere?
g
There are
I mean that you still can publish API reference using Dokka just as HTML or as Javadoc format
I suppose most of libraries don’t have empty javadoc because use default Gradle javadoc tasks that generates empty output for pure Kotlin project But still publish it, because Maven Central doesn’t allow publish libraries without javadoc
d
That's what I also suspect - that by default Gradle isn't doing what many would expect to be the 'right' thing
g
If you generate javadoc from Maven for Kotlin project you will probably get exactly the same result
d
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.e. one that is expressive for Kotlin-specific API info, and could be publishable as another documentation type on Maven repos)
g
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
d
@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.
d
Many thanks for looking
3 Views
Open in Slack
PreviousNext
Powered by