If I run javadoc on a set of source files, I get that wonderful HTML output we all know and love. However, it appears there is no way to add more output incrementally. That is, if I run javadoc on Main.java, then later add Sub.java, I can't just run javadoc on Sub.java and have the resulting output show the documentation on both Main and Sub. Apparently, the only way to do it is to run javadoc on Main.java and Sub.java as a single run of javadoc. Likewise, if I want to produce the HTML for multiple packages, I have to specify them all on a single command line.
Finding this hard to believe, I went to the javadoc home page, where it says rather unequivocally, in answer to the question, "Can I incrementally build a document from different runs of Javadoc?", that the answer is, "Basically, no."
Okay, I can read, so I get it. But... I still find it hard to believe. Are they saying that, if someone at Oracle finds a typo in the javadoc for the Executor class in the java.util.concurrent package, that javadoc must be run on all of the ~250 packages (and all of the ~3600 classes and interfaces) documented already? Anyone know of a way to consolidate the results of two javadoc runs?
In the other disciplines, we rise by standing on each others' shoulders. In computer science, we do it by standing on each others' toes.
Stevens Miller wrote:... Are they saying that, if someone at Oracle finds a typo in the javadoc for the Executor class in the java.util.concurrent package, that javadoc must be run on all of the ~250 packages (and all of the ~3600 classes and interfaces) documented already?
No, they just run the javadoc on the one file with -link to the rest of the javadocs, then copy the result file to replace the Executor page in the already present javadocs.
That doesn't help when you add new things to the project, of course. But that should be rare for something like an API.
Ah, that's clever. Reminds me of the days when we used to patch IBM system code by replacing blocks of instructions with new machine language of the exact same length. As long as we didn't disturb anything else, the changes fit right in.
The -link option was kind of puzzling to me, but I can certainly see how it could work as you describe. Your other point is well taken: packages and classes may come and go between releases, but it would defeat the purpose of even having an API if, within a given release, whole new classes might suddenly be added.