Javadocs Are Disappearing

Question

I just whipped up a medium-sized utilities JAR to be used by many other Eclipse projects. I spent a good deal of time writing tedious javadocs so that it would be pretty obvious how to use the API.

I used Ant to throw everything in a JAR, and I am now adding that JAR to the build path of a new project. But low and behold...when I mouseover any of my utility classes/methods, the tool tip that pops up says:

Note: this element neither has attached source nor attached Javadoc and hence no Javadoc can be found.

What is going on here? What's the solution? Here is the dist Ant target that JARs up my utilities project:

<target name="dist" depends="compile">
    <jar jarfile="dist/testing-utils.jar">
        <fileset dir="bin/main" />
        <fileset dir="src/main/config" />
    </jar>
</target>

What else do I need to configure?!? Thanks in advance!

score 3 · Accepted Answer · edited May 23 '17 at 12:29

3

The java compile task, which I assume you're using in the "compile" target, generates bytecode from your Java source. This bytecode will not include comments by design and thus your distribution jar will not include comments.

What you are probably looking for is to attach the source in Eclipse to get access to the Javadocs. You can attach source to your library jars by right clicking on the target jar, selecting properties, select Java Source Attachment and provide the location of the source jar. You can also provide a folder location, if you want to reference your project directly.

To generate a Jar that includes javadocs and source, you may use the following in ant:

<target description="bundle sources in a jar" name="package-sources">
    <jar basedir="src" destfile="build/release/${ant.project.name}-${project.version}-sources.jar"/>
</target>

Reference

edited May 23 '17 at 12:29

Community

1
1

answered Dec 23 '11 at 21:37

John Ericksen

10,995
4
45
75

Thanks johncarl - I've seen these "source bundles" before but never knew what they were. Would that just include the source and javadocs or would it also include the binaries? – IAmYourFaja Dec 23 '11 at 21:47
That ant snippet I included would only include the java source. I don't think I've seen a jar with both source and binaries in the same artifact. As a Maven user I regularly see source and/or javadoc jar artifacts available in the central repository, which facilitates the functionality you are looking for. – John Ericksen Dec 23 '11 at 22:01
Anther point, you may also use the ant Javadoc tool to create a javadoc only artifact: http://ant.apache.org/manual/Tasks/javadoc.html – John Ericksen Dec 23 '11 at 22:02

score 0 · Answer 2 · answered Dec 23 '11 at 22:02

If you do want to ship sources then johncarl's answer is probably correct; it is the first of the two options offered by eclipse -- attached sources. If you don't want to ship sources then you need to generate javadocs, see the ant javadoc task. With that approach, you would have two jars, one containing the compiled classes and another containing documentation. In eclipse, your users will add the class jar to project and then attach to it the javadoc jar.

Javadocs Are Disappearing

2 Answers2