What would be a good alternative to inline Java documentation, i.e. can one have a separate docs file somehow mapped to a java source file?
I have never liked huge comment sections littered in code.
I have been using Javadoc feature of package comments to avoid littering source code with verbose documentation comments:
Using above feature, I had detailed verbose documentation for classes and methods in the package stored separately of code, in a dedicated html file. As for Javadoc comments in java files, I just wrote brief explanations there, adding text like
One thing I particularly liked about this was that although docs were in the separate file and in a format more convenient for large docs (html), it has been stored close enough to related source code and all the updates in it were automatically picked up during the build.
Starting from Java 1.5, you can alternatively put a
JLS documentation suggests that this is preferred way:
If anybody reads them. Especially if you have "huge comment sections littered in code" ;)
In short, the best way to have comments is keeping them short, clear and have them explain the why. This is done by making your code and unit tests super clear.
One exception to this are exposed interfaces. Your user needs explanations to be able to use your tool/library: you can't ask him to read your code.