Why JAR Files Do Not Contain Documentation?

Question

I'm in the process of writing a small Java library that contains a related code that I usually include in most of my android app. I decided to export the library as a jar file then drop the file in the libs folder of my future projects.

Using Android Studio:

I created a Java Library module and put my code in it. And I added some comments to some of the method, following this.
Then, I ran the jar task in gradle, which gave me the .jar file in build/libs directory of my module.

Now, when I used this jar in one of my android apps, Everything works as expected, except the Doc part. When I hover over the classes and methods of my library, I don't see the Doc comments that I wrote.

Q1: Am I missing another step?
Q2: Are jar files supposed to have no comments?

@Prashant But Javadoc task will generate html Doc. My goal is to allow the user of the jar file to see Doc comments in the editor. Is this possible? — iTurki, Aug 22 '15 at 05:44
@Prashant I couldn't figure out how to do that. Should I pass a specific parameter to the task? Or run a different task? — iTurki, Aug 22 '15 at 05:56
@Prashant Running a `jar` task does not prompt me for anything. — iTurki, Aug 22 '15 at 06:04
Some JAR files *do* contain documentation, and there is nothing stopping you from creating such a one yourself, but most JaR files contain object code only. — user207421, Aug 22 '15 at 08:06

Stephen C · Accepted Answer · 2021-08-24T22:45:24.817

The javadocs are the documents that are generated from the javadoc comments in your source code. They are not part of a normal JAR file because that would unnecessarily bloat the JAR files ... with stuff that someone running to code doesn't need.

The javadocs can be generated by a Gradle task, by the javadoc command (if you have a Java SDK installed) and by various other tools. You can then read them using a web browser.

On the other hand, IDEs can often render the javadoc comments in source code and display them as pop-ups, etcetera. (Some people would call this "javadocs", but I think that is an overstatement, since you typically can't navigate the documentation ... like you can with read javadoc documents.)

In order to render the javadoc comments, the IDE needs the source code. JAR files don't (normally) contain any source code or javadocs. Instead, the normal way to deal with this is to tell the IDE where the source code is, either by pointing it at a source code directory, a ZIP file containing source code, or URL for downloading the source code.

(I don't use Android Studio, so I can tell you exactly how to do this. However, I imagine that the IDE's online help explains how to do it ...)

It seems that your end goal here is to distribute your libraries in a way that allows programmers to see the javadoc comments.

The simple way to do that is to distribute source code. This Q&A describes how to get Gradle to generate a separate archive containing the source code, or add the source code to the JAR containing your compiled code¹.

If that isn't acceptable, you may need to generate the javadocs as HTML² and provide the HTML tree as a separate ZIP file that a programmer can unzip and read with a web browser. Alternatively, put the javadocs up on a website.

^{1 - I would not recommend this. People who just want to use the JAR as a binary are liable to complain about "bloat".

2 - If neither providing source code or javadoc HTML documentation is acceptable, I don't think there is a pragmatic solution.}

Distributing the source code is fine. However, I couldn't figure out which task will do this for me. Is it the same `jar` task with special parameters? Or a totally different task? — iTurki, Aug 22 '15 at 05:58
Read this Q&A - http://stackoverflow.com/questions/11474729/how-to-build-sources-jar-with-gradle — Stephen C, Aug 22 '15 at 06:21
Thanks for sharing! [This answer](http://stackoverflow.com/a/26261956/543711) did it for me. Please edit your answer with the link so I can accept it — iTurki, Aug 22 '15 at 06:32

Koby · Answer 2 · 2015-08-22T07:01:14.540

0

There is a separate Gradle task to generate javadoc. Try adding the following:

task javadocJar(type: Jar, dependsOn:javadoc) { 
 classifier = 'javadoc' 
 from javadoc.destinationDir }

And then run:

gradle javadocJar

See if that helps.

In addition to the above, you can try and add the following to make to generate a single jar with both compiled classes and javadoc:

jar {
    from javadoc.destinationDir
}

jar.dependsOn javadoc

I don't know if that's the right decision to bundle everything in the same jar. I prefer keeping the jars separate and maybe find another way to make the IDE use the javadoc jar file. Maybe try adding the javadoc jar as another dependency of the module.

edited Aug 22 '15 at 07:01

answered Aug 22 '15 at 05:16

Koby

605
5
11

Ok. I found the Task, but it seams that all it did was generate a html version of the Docs. – iTurki Aug 22 '15 at 05:28
I should add the task to the library build.gradle, right? – iTurki Aug 22 '15 at 05:52
What do you mean by library? It should be added to your project's gradle file. – Koby Aug 22 '15 at 05:54
I mean the gradle file for the module (library) or the top level (Project)? – iTurki Aug 22 '15 at 05:57
Try the module first. If that helps you can add to all modules by using allprojects/subprojects as explained here: https://docs.gradle.org/current/userguide/multi_project_builds.html. – Koby Aug 22 '15 at 06:04
Ok. This does generate a javadoc jar file next to the library jar. However, adding the two jar files to the lib folder of a project is not enough. You need to attach the javadoc jar to the library jar. – iTurki Aug 22 '15 at 06:20
See my answer again. I've re-edit it and added a way to bundle everything in the same jar. – Koby Aug 22 '15 at 07:02

score 0 · Answer 3 · answered May 06 '22 at 20:08

Yes This is possible

Hi, This is possible but with a small change like in the jar file.

First of all, from a code point of view jar file contains only compiled ".class" files and not source files ".java"

So if you need a doc to be applied with a jar by this I mean not the index.html which gets created but the comment that appears whenever a person uses the jar API and calls a method with a suggestion.

Example :