Packaging documentation with jar file

Question

We are porting our .NET library to the java equivalent and are now looking at how to allocate this port. Packing classes into a jar file seems like best practice, and we will send this jar file to zip along with some license terms.

But what about documentation? In the .NET environment, it seems best practice to distribute an XML file that can be used with tools (Visual Studio), but we cannot find such best practices for java. We have javadoc comments about our public classes and interfaces, so we are just looking for a way to generate and distribute these comments in a way that makes it developer friendly (we think it is easily consumed from different IDEs). What are the developers expected and how do you best do this?

We really would rather combine the documentation with the jar file and not post the documentation on our website

EDIT: We would like our documentation to appear inside the java-IDE, so we want to provide the documentation in such a way that it integrates as much as possible into the IDE. In the .NET environment, it's like an XML file located next to a DLL file, but is there a similar concept for jar files that allows integration into tools?

PS: We are developing in Eclipse and have an ant task that builds a building and a jar file in our automatic build.

Answer 1

A common way is to create a doc folder within which you create a JavaDoc for your project.

Your last package looks like this:

finalpackage.zip:

• product.jar
• doc
• LICENSE
• Other things

Maven makes this easy, but a tool like Ant can also be easily customized for this. Obviously, there is also a manual way, but he recommended including it as part of the build process.

Answer 2

The most common way to provide documentation is to create a javadoc site visible from the Internet. The most obvious way to do this is to invoke the ajvadoc command for your project. Thus, a complete site will be created. But, in order to synchronize it with your code, I would recommend that you go to the full path of creating an enterprise and create a maven build for your project. Thus, when creating a commercial version (the mvn release team), a complete documentation site will be created with all the reports related to your project.

Answer 3

I think the most common way to provide javadoc and jar sources is for you. Using maven, you can run mvn dependency:sources , and the IDE should provide you with all the context-sensitive help with your library. And of course, javadocs should be available over the Internet.