Packaging reference documentation with jar file

Question

We are porting our .NET library to a java equivalent and is now looking at how to distribute this port. Packaging the classes into a jar-file seems like best practice and we would then ship this jar file in a zip along with some license terms.

But what about the documentation? In .NET land it seems like best practice to distribute the xml file that can be consumed by tooling (Visual Studio) but we can't seem to find such best practices for java. We have javadoc comments on our public classes and interfaces, so we are just looking for a way to generate and distribute these comments in a way that is developer friendly (we're thinking easily consumed from various IDEs). What are developers expecting and how do you best deliver this?

We would really prefer to bundle the documentation along with the jar file and not have to host the documentation on our website

EDIT: We would like for our documentation to appear inside the java IDEs so we want to provide the documentation in a way that integrates into the IDEs as gracefully as possible. In .NET land this is as an xml file placed next to the .dll file, but is there a similar concept for jar files that enables the integration into tooling?

PS: We are developing in Eclipse and have an ant task doing the building and jar-file packaing in our automated build.

Answer 1

The most usual way to provide documentation is to create a javadoc site, visibile from the web. The most obvious way to do so is to invoke the ajvadoc command on your project. This way, the full site will be generated. But, to have it synchronized with your code, I would recommand you to go the full enterprise build way and to create a maven build for your project. This way, when creating a commercial version (the mvn release command), a full documentation website will be created with all the reports concerning your project.

Answer 2

A common way is to create a 'doc' folder, under which you generate the JavaDoc for your project.

Your final package then looks like this:

finalpackage.zip:

• product.jar
• doc
• LICENCE
• Other stuff

Maven makes this easy, but a tool like Ant can also be easily be set up to do this. Obviously, there's also the manual way, but it's recommended to include it as part of the build process.

Answer 3

I think the most usual way it's to provide javadoc and sources jar for you library. Using maven then you could execute mvn dependency:sources and IDE should give you all context sensitive help with your library. And of course javadocs should be accessible via web.