okhttp
okhttp copied to clipboard
square
Fix javadoc publishing of maven artifacts
The sources artifact published to Maven Central only contains Kotlin files. The javadoc artifact is empty.
Consequently, users cannot look up the Javadoc of a method from within the IDE and code-completion provides ugly parameter names like HttpUrl.get($this$toHttpUrlOrNull).
Please publish full Javadoc to Maven Central. Hopefully that will fix parameter names and let users look up the Javadoc on the fly.
(I personally consider this issue to be a bug, not a feature request, but I leave it up to you to decide)
@cowwoc The sources artifact should only contain kotlin files. OkHttp is implemented in Kotlin.
Could hook up dokkaJavadoc for the Maven artifact. https://blog.jetbrains.com/kotlin/2020/08/dokka-preview-based-on-kotlin-1-4-0-rc/
Hopefully it's improving but when I looked at this previously the upgrade wasn't a tap in
https://github.com/square/okhttp/pull/6342 https://github.com/Kotlin/dokka/issues/1592
@swankjesse Normally I like to be able to debug into the source-code, but so long as the method, parameter names are correct with Javadoc I think it's fine :)
@cowwoc source appears to be publishing fine https://repo1.maven.org/maven2/com/squareup/okhttp3/okhttp/4.9.0/
Likely there is something else going wrong with your IDE stopping this working. It works correctly for me in downstream projects with Intellij. It contains all the source code as *.kt files.
But publishing javadoc artifacts should be fixed.
@yschimke The sources are there but if you CTRL+LMB click in IDEA it will open the decompiler instead of the sources. This is likely a side-effect of your usage of Kotlin. Adding Javadoc should be enough I guess.
I think if you just create your own dokka task and name it javadocJar before calling withJavadocJar() it'll work fine out of the box.
@ansman I'm not an expert on dokka, if it's that simple we'd happily accept a PR enabling that. I held off previously because dokka had a big rewrite, but that sounds great!
It is that simple, unfortunately dokka 0.10 does not support javadoc generation on JDK 11. I tried upgrading to dokka 1.4.20 but I hit the same issue as you filed: https://github.com/Kotlin/dokka/issues/1592
Working for 5.0, closing as low priority. Sorry.
https://repo1.maven.org/maven2/com/squareup/okhttp3/okhttp/5.0.0-alpha.11/