When programming in C++, I use Doxygen and frequently create external .dox files for additional documentation that won't fit well in a specific class or method - for instance, file format documentation (for files that are accessed by multiple classes). I tried to find a way to do the same in Java, but it appears that javadoc doesn't have an equivalent feature, all documentation must be written inside the comments of a .java file and is tied to it (or at least to its package). Am I right? Is there an alternative way to do this?
+2
A:
If you're asking if Javadoc can create external documentation, then the answer is no. But you can link to external documentation you've already made. Additionally, if something applies to the package level, you can put the documentation in the package file instead of attaching it to a particular class or method.
John Feminella
2009-03-09 02:33:34
What do you think about creating a package and classes just to contain such bits of information (I mean, empty classes that aren't used by anyone, just to have a place to put these docs). Would it be too ugly?
Fabio Ceconello
2009-03-09 19:28:11
Yes, I think that would be an error. Don't pollute your source code for the sake of documentation! :)
John Feminella
2009-03-09 23:37:51
What about a script that takes a comment file - let's say a .jdoc, wraps it in a temp .java file with a stub empty class, runs javadoc compiler and then deletes the temp file?
Fabio Ceconello
2009-03-10 18:00:04
I'd say that one is more just a clever use of the javadoc compiler than polluting your source code, so I don't think there's any issue with that. Just make sure it doesn't affect any real code!
John Feminella
2009-03-17 13:26:40
+3
A:
The section “Miscellaneous Unprocessed Files” from the javadoc documentation is what you’re looking for.
Bombe
2009-03-09 08:57:24
Thanks, I knew about MUF but I was looking for something a bit different. What I miss is that when you create a .dox file for Doxygen you can use the same syntax (you can put @see, @version, etc.) inside the .dox to link to/from it, and with a static HTML this would not be possible.
Fabio Ceconello
2009-03-09 19:24:03
Correction - of course you could put an HTML link, but it wouldn't be updated if the linked item is moved.
Fabio Ceconello
2009-03-09 19:25:57