Java tools to create enterprise application documentation

Question

This question is a bit vague but I'd like to know if there's a Java tool that can run through my code and document it in a functional way. Is JavaDoc the only way to go, or are there alternatives?

Answer 1

JavaDoc is a good way of generating reference documentation. You can use custom doclets to adapt it to your needs (in look, functionality or extra bells-and-whistle) but it is still essentially still a list of methods and their descriptions.

Documenting enterprise software is more about documenting higher level stuff like design information, architecture, component interactions, etc. There's no software tool I know of that will do this for you automatically (reverse engineering tools will mostly produce a mess), but there are many content management systems that can help you organize and present it better.

You could also write a JavaDoc alternative (or use something existing) that uses reflection to analyze a class library and produce stuff, possibly with your help via annotations. For instance, there are research tools that let you place architectural constraints within your code, that are then used for conformance testing and possibly for documentation.

Answer 2

It all depends on what you want out of the generated documentation. JavaDoc is the standard way to do API documentation in Java, so that's probably your best starting point. There's actually a Doclet API if you just need to tweak the output. One example of the Doclet API in action is the UMLGraph doclet that can embed UML graphs in your JavaDoc output.

If you just hate JavaDoc, there's always things like Doxygen.