Imagine you would describe exactly what happens within a method or class. You could generate JavaDoc and be able to understand the inner working of a method without reading the code.
However, human language is too ambiguous to exactly describe a program or algorithm. The next improvement would be to introduce a more precise language. You could use a DSL or a pseudo language to eliminate the ambiguity and very precisely describe a method.
After a few iterations you could even make the documentation executable …and miss the whole point:
Developers would prefer to read straight Java code over a pseudo language. Only a few developers (I do not know any) like to read extensive documentation. Also: in case the documentation exactly describes the software, there is no added value left. You could equally easy read well written code of any high level language.
The only way to write readable documentation is to describe the non-obvious and the intentions behind a strange piece of code.
Documenting the obvious is a defect.
This post was inspired by Adam's Walczak comment. Thanks!
See you at Java EE Workshops at MUC Airport, particularly at http://workshops.adam-bien.com/javaee-architectures.htm!
NEW online workshop: WebStandards Igniter (online)