Javadoc is missing completely. Intellij "Jump to source" does not work

[stargazer33]

Steps:

1. Adding this to pom.xml (at the time of writing: the 0.8.1 still not available in mvnrepository.com):

    <dependency>
      <groupId>com.openai</groupId>
      <artifactId>openai-java</artifactId>
      <version>0.8.0</version>
    </dependency>

2. build project with maven

3. Run this:
   mvn dependency:sources dependency:resolve -Dclassifier=javadoc

4. Check local repository:

ls -l ~/.m2/repository/com/openai/openai-java-core/0.8.0/*.jar
-rw-rw-r-- 1 <user> <user>     261 Dec 17 19:25 /home/<user>/.m2/repository/com/openai/openai-java-core/0.8.0/openai-java-core-0.8.0-javadoc.jar
-rw-rw-r-- 1 <user> <user>  336086 Dec 17 19:25 /home/<user>/.m2/repository/com/openai/openai-java-core/0.8.0/openai-java-core-0.8.0-sources.jar
-rw-rw-r-- 1 <user> <user> 3088181 Dec 17 19:25 /home/<user>/.m2/repository/com/openai/openai-java-core/0.8.0/openai-java-core-0.8.0.jar

ls -l ~/.m2/repository/com/openai/openai-java/0.8.0/*.jar
-rw-rw-r-- 1 <user> <user> 261 Dec 17 19:25 /home/<user>/.m2/repository/com/openai/openai-java/0.8.0/openai-java-0.8.0-javadoc.jar
-rw-rw-r-- 1 <user> <user> 302 Dec 17 19:25 /home/<user>/.m2/repository/com/openai/openai-java/0.8.0/openai-java-0.8.0.jar

This means - Javadoc is always empty! (there is no Javadoc in these 261 byte big files)
There are sources in openai-java-core-0.8.0-sources.jar - but it can not be viewed in Intellij, see below

5. Using IntelliJ IDEA 2024.3:
   Pointing cursor over OpenAIClient, ChatCompletionCreateParams -> no Javadoc for these classes.

"Jump to source" for these classes: it opens decompiled .class file. Clicking "Download sources" in Intellij - does NOT help!

RESULT:
Without Javadoc and without sources - this library is quite difficult to use!

[TomerAberbach]

Thanks for the report!

I'll fix this in the new year :)

[TomerAberbach]

So in IntelliJ, if I click on "Download documentation" in the tooltip when hovering over a symbol, then it does work. I get documentation when hovering over symbols and I can also jump to source. Are you seeing something different?

Regarding the empty javadocs JAR, apparently that's a known behavior of Kotlin libraries, but people seem to generally consider it a non-problem because downloading the sources (e.g. via the "Download documentation" button I mentioned) results in having the javadocs. Perhaps it's still worth looking into, but I would first be interested to understand if what I described above works for you, because it works for me.

[stargazer33]

1. Attached the video of IntelliJ:
   https://github.com/user-attachments/assets/b9236863-6599-4dee-8b4a-1a5cd1f1e1f1

This is a new, empty project just with one dependency, the 0.8.1 is available since today/yesterday.

In this project I do
Maven->Sync project
after this
Maven->Download documentation
after this:
Hover cursor over ChatCompletionCreateParams -> NO documentation
Hover cursor over String -> documentation pops up.

[stargazer33]

We are not debugging IntelliJ: this road leads nowhere. There are 1mln ways to configure IntelliJ, easy to get lost.

Let us see what can be done with pure command-line and maven: this is quite easy to reproduce.

I did again:

mvn dependency:sources dependency:resolve -Dclassifier=javadoc

Still can not see this JAR file with documentation under
~/.m2/repository/com/openai/openai-java/

What is the full path to this file on your machine ?

[stargazer33]

IntelliJ is looking for exactly these files, see screenshots.
And exactly these files are 261 byte big in the filesystem.

[TomerAberbach]

I want to note that ChatCompletionCreateParams, which you hovered over in your video, specifically happens to not have any documentation, so the fact that it doesn't show up isn't related to the empty javadocs:

openai-java/openai-java-core/src/main/kotlin/com/openai/models/ChatCompletionCreateParams.kt

Lines 31 to 32 in 2b735f9

	class ChatCompletionCreateParams

I think right now we have some documentation on the service method that ChatCompletionCreateParams corresponds to, but not ChatCompletionCreateParams itself. Perhaps I should duplicate that javadoc so that it's available from both places. Thanks for surfacing that!

OpenAIClient also has no documentation on it right now.

Can you try hovering over something like model of ChatCompletionCreateParams.builder().model(...)? The model method has documentation.

---

Regarding the empty javadocs JAR, as I mentioned above, it seems expected for Java libraries written in Kotlin to emit empty javadocs JARs:

Regarding the empty javadocs JAR, apparently that's a known behavior of Kotlin libraries, but people seem to generally consider it a non-problem because downloading the sources (e.g. via the "Download documentation" button I mentioned) results in having the javadocs.

So if you still don't see documentation, then the question is why your documentation is not appearing even if sources are downloaded, since the sources have the documentation too.

[stargazer33]

Well, here move videos with attempts to view documentation/sources, this time - on .model() method:

v2.webm.mp4

v1.webm.mp4

[stargazer33]

Well,

... it seems expected for Java libraries written in Kotlin to emit empty javadocs JARs"

... people seem to generally consider it a non-problem because downloading the sources (e.g. via the "Download documentation" button I mentioned) results in having the javadocs."

this proves nothing.

Unless you have invented a magical way to transfer sources and documentation to other computers, sources and documentation are transferred using FILES.

As the author of this library, you know where these files are.
Therefore:
the full path to the documentation files should be.... ?
the full path to the source files should be... ?

[TomerAberbach]

We now have javadoc in the jar as well as javadoc.io docs

There are still many things undocumented, but we'll be adding more documentation over time. Please be patient; this is an alpha release :)