3

Generally, when publishing a library, do we need both sources.jar and javadoc.jar? I don't really understand the purpose of javadoc.jar.If it's about the code documentation, the IDE can show it from sources.jar itself.

Example: enter image description here

Please note, this is not a duplicate of What are the differences between javadoc.jar, sources.jar and .jar?. I am looking for what javadoc.jar can do, that sources.jar can't.

theapache64
  • 10,926
  • 9
  • 65
  • 108
  • 3
    What happens if I do not want to share my code with you? What happens if my code is unread-ably bad? What happens if I want to make my docs multi-lingual? – Scary Wombat Sep 28 '21 at 08:07
  • @ScaryWombat Makes sense. do you have a reason why most libs publish both javadoc and sources jar? – theapache64 Sep 28 '21 at 08:10
  • @ScaryWombat Also, Apart from that, is there any IDE (IntelliJ) benefit we can gain from `javadoc.jar`? – theapache64 Sep 28 '21 at 08:12
  • Note that your posted question and the one in your comment have different audiences: "why do we need (to create) javadoc jar?" targets the authors of the code and Scary Wombat already answered that. "What benefit do I get from javadoc.jar in my IDE" targets the users of your library and from a personal point of view I'd say you should try to get the sources if you can as this can help with debugging. – Thomas Sep 28 '21 at 08:13
  • On "why do most libs publish both?": Note that javadoc.jar also contains the compiled HTML pages for the Javadoc so if someone just wants to host those without having to build them from the sources they can just grab the jar. Sometimes organizations don't allow access to external (source) code for security reasons. (The example might be somewhat off but the question seems to be similar to "why don't libs just publish the sources and let you compile the lib?"). – Thomas Sep 28 '21 at 08:19
  • Understood @Thomas. Thanks for the explanation with real-world scenarios. If you want to merge the comments to an answer, I'd love to accept that. – theapache64 Sep 28 '21 at 08:25
  • @ScaryWombat you actually answered the question first, so feel free to compile the comments into an answer :) – Thomas Sep 28 '21 at 08:28
  • I'll add an answer myself so you can accept and close the question. If ScaryWombat adds one as well, feel free to accept that one instead of mine :) – Thomas Sep 28 '21 at 13:38

2 Answers2

3

Let me address the questions one by one:

Why does javadoc.jar even exist if sources.jar can be used?

This question basically addresses the developers. If the sources can't be shared (e.g. it might be proprietary) sharing the documentation is still going to help.

Why do developers provide both?

A very simple reason might be because that's the default for Maven, Gradle etc.

Another reason might be that some organizations don't allow access to source code for security reasons (or others) or can't/don't want to build the HMTL files themselves but rather just host them.

Why do I as a developer need to import javadoc.jar into my IDE if I can use sources.jar?

I'd say you shouldn't need to. As a dev I often find it very useful to have the sources available for debugging etc. so I'd prefer source.jar.

Thomas
  • 87,414
  • 12
  • 119
  • 157
  • Source code is not generally self-explanatory. Take, for instance, `public void notifier(String target1, String target2)`: What or who does it notify? Are `target1` and `target2` receivers or services? There is no type info in `String` to help identify the meaning of the targets. This is why mnemonic naming is important, and it's also why Javadoc is very necessary. – ingyhere Oct 01 '21 at 04:23
  • @ingyhere well, normally the sources contain the (unprocessed) Javadoc as well. – Thomas Oct 01 '21 at 08:22
0

The sources JAR and the Javadoc JAR serve fundamentally different purposes.

  • The sources JAR will allow the IDE to present solutions for code completion, lists of required and optional arguments with their corresponding types, etc. EXAMPLE: Source for Jenkins server
  • The Javadoc JAR provides a Web-based encyclopedia of the API being used. So if one is curious about all the various constructor invocations, one can read about it. If one is curious about the inheritance hierarchy, they can jump through documentation pretty easily in HTML format. Notably, an IDE might provide Javadoc as documentation excerpted and linked to source solutions but does not show interrelationships or details as well. EXAMPLE: Javadoc for Jenkins server

A complete representation of the product that is developed against should include both source and javadoc for the precise explanatory reasons detailed above.

ingyhere
  • 11,818
  • 3
  • 38
  • 52