File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Beginning Java and the fly likes Can the output from two javadoc runs be consolidated? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Soft Skills this week in the Jobs Discussion forum!
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "Can the output from two javadoc runs be consolidated?" Watch "Can the output from two javadoc runs be consolidated?" New topic
Author

Can the output from two javadoc runs be consolidated?

Stevens Miller
Ranch Hand

Joined: Jul 26, 2012
Posts: 567
    
    4

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?
Steve Luke
Bartender

Joined: Jan 28, 2003
Posts: 4181
    
  21

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.


Steve
Stevens Miller
Ranch Hand

Joined: Jul 26, 2012
Posts: 567
    
    4

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.

Great answer. Thanks.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Can the output from two javadoc runs be consolidated?