22

I am writing a custom library. It's build into a .jar archive. I am fully able to generate the javadoc, but I don't know how I should distribute it?

  1. Put it in the same .jar with the library
  2. Put it in a different .jar
  3. Some other way?

And how to include the javadoc in another project that uses my lib?

  1. If I had put it in the same .jar, should I have written something in the manifest?
  2. If it's in a separate .jar, is including it in the project enough?

I am using NetBeans 9.1.

pjs
  • 18,696
  • 4
  • 27
  • 56
Albus Dumbledore
  • 12,368
  • 23
  • 64
  • 105

3 Answers3

21

I'd include the library .jar and the documentation and other things, like a README, License file etc. in a single archive (zip or tar.gz)

mylib-1.0.1.tar.gz , which contains:

mylib-1.0.1/
           ├── javadoc
           │   └── index.html  (and all other javadoc files under here)
           ├── mylib-1.0.1.jar
           └── README

Instead of the expanded javadoc/ sub directory within the archive, you could add the compressed javadoc in a mylib-1.0.1-javadoc.jar (or zip) , both options are common.

mylib-1.0.1/
           ├── mylib-1.0.1-javadoc.jar
           ├── mylib-1.0.1.jar
           └── README
nos
  • 223,662
  • 58
  • 417
  • 506
  • 2
    the javadoc consists of many files, so I'd prefer it compressed and archived. On the other hand, it's my fault that I though that it may be something special as I thought that the "add jar/zip" command in netbeans was only for libraries, but it's for virtually any resource. Thanks! – Albus Dumbledore Oct 07 '10 at 10:44
  • If you do it like this, Eclipse is able to link to the Javadoc from references. Good method indeed. Also is what Maven repositories tend to do: http://search.maven.org/#browse|1803601404 – Ciro Santilli OurBigBook.com Feb 02 '15 at 15:51
3

It's a general practice to keep the JavaDocs in a separate archive. or even more commonly, in a directory called 'docs'. you do not needlessly want to bloat your library's archive with the html and js files.

And why would you want to include the generated JavaDocs [html + js] in your project? As long the source code JavaDoc comments are in place, someone using your library will be able to see them by simply hovering over w/ the mouse in any of the modern IDE's

Update
As per nanda's comment below, I checked the same and he IS correct. In my project, I have actually attached Javadocs from the 'doc' folder to the archive to be able to view them on mouseover.

anirvan
  • 4,797
  • 4
  • 32
  • 42
  • 8
    not true... if you compile the java classes normally you will lose all comments. Even IDE can't recover it. You should include the source in another jar IMO. – nanda Oct 07 '10 at 10:50
1

Another way: For me this was the best choise: (addingto build.xml. I've tested it on NetBeans IDE 7.0 and 7.2.1) (found it on Automatically generating source and doc jars in Netbeans )

<target name="-post-jar" description="bundle sources and javadoc in a jar" depends="javadoc">
<jar compress="${jar.compress}" basedir="${src.dir}" jarfile="${dist.dir}/${application.title}-sources.jar"/>
<jar compress="${jar.compress}" basedir="${test.src.dir}" jarfile="${dist.dir}/${application.title}-test.jar"/>
<jar compress="${jar.compress}" basedir="${dist.javadoc.dir}" jarfile="${dist.dir}/${application.title}-javadoc.jar"/>

This will create four jars, one to application program, one to sources, one to tests and one to javadoc.

Community
  • 1
  • 1
Cristhian Guedes
  • 57
  • 9