Merge the JavaDoc instead
On a recent project we had a similar problem. We used 13 different JavaDoc trees of documentation and it was a pain to search and find the appropriate documentation.An alternative that I came up with was to just merge the JavaDoc into a single hypertext tree of JavaDoc pages. The idea was to conceptually overlay all of the directory trees and files into the one directory structure. When you do this, most of the files have unique names, given by their position in the package structure and by their (class) names. Also, a number of the Java classes had very unique names that are only ever referenced in one of the root JavaDoc trees. Since these files were unique, I could copy them to the merged JavaDoc directories but since a number of unique Java class names exist I could increase the hypertext links between the original 13, separate JavaDoc trees. So I used HtmlParser (open source) to parse the source HTML, and add extra hypertext links to the unique Java class names.There were, however, a number of HTML files between the various 13 JavaDoc trees that had the same name and position within the tree structure. The best that I came up with was to simply append one file onto the end of the other, adding some navigation tags to leap to the start of the appropriate section (using in-page HTML link tags) and write the contents into the same position within the merged JavaDoc tree structure. This just left writing the top-most HTML pages (index.html, etc) to link it all together.The whole tool took about 5 Java classes and the open source HtmlParser library to get it working. While it is not a perfect solution, it certainly made access to the JavaDoc a lot simpler and a more rich set of documentation at that. It has one other advantage, we could script the build of the documentation using Ant and be assured that the merged JavaDoc documentation matched exactly the application and utility classes being used on the project.

JavaDoc needs to be shelved, projects should serve a presentation neutral documentation format

Problem with this approach is dealing with upgrades. I'd prefer a solution that leaves JavaDoc in place (at the provider). This way, when you need to upgrade a particular component, such as Jakarta Commons BeanUtils from 1.6 to 1.7.1, you don't have to run some sort of merge process to upgrade your tree.

Unfortunately, the problem is deeper than just aggregating JavaDoc. JavaDoc's problem begins with the fact that it is 1. HTML, and 2. Presentd using Frames. Instead of generating JavaDoc, Java documentation should be exposed as a presentation neutral XML format. Someone should then create a rich client application to aggregate and present the documentation in the format of choice. David Flanagan has done some great work presenting JavaDoc as it appears in the Nutshell series.

eating your own words?
>BTW, I know. I'll eat my own words on AJAX

Is this based on any reason other than that you're just giving in to the unstoppable hype machine? I was about say developers are like sheep, but I think I'm wrong...developers are a bit easier to herd into the next "big thing".

Dismiss AJAX at your own peril

tcowan, it is based on real experience. After having used Flickr in a work-related way over the past few weeks, I can say that the AJAX specific features of the aforementioned site have saved me a considerable amount of time (== money). From a usability standpoint, the AJAX approach will always gain the user's vote. And, there's the rub, the user will expect to be able to [sort|edit|hide|drag] stuff on the screen without having to wait 2-3 seconds for your slow application server to query the database and re-render everything on the page just because you clicked on a column to sort a little table on a website.

So what you can do stuff on a web page and it doesn't have to reload? What's the big deal? The difference is as striking as the difference between Gopher and Mosaic. We've made a generational shift, and we're moving on. Contrary to what I thought a few months ago, AJAX isn't the "next big thing", it's already come and gone and the people who figured that out have a huge jumpstart on the rest of us.

Do I still think it is a mistake to throw server-side developers at Javascript without serious training wheels? Yes. But, after seeing the array of available AJAX frameworks, most of my concerns about AJAX have been addressed.

No doubt; developers of web applications not using AJAX in some capacity are building yesterday's applications. This will become more and more apparent over time as you realize that usability trumps all. Really, AJAX is to Page Reloading as SpaceShipOne is to a tricycle.

Saying it again for emphasis, if you are developing a web application, and you are not using AJAX in some capacity, pack the contents of your cubicle into a set of four cardboard boxes and consider a career change. This may seem to be a trivial thing to us "programmers" but it's going to be a showstopper for those pesky users.

So, the internet is about a generation old at this point, and there are a number of "changes" that people will need to either accept voluntarily, one of them is REST and the other AJAX. Dismiss them as buzzwords at your own risk.

JavaDoc needs to be shelved, projects should serve a presentation neutral documentation format
I am using a JavaDoc-a-like for ActionScript, and it has an option to output the docs in XML. I assume it is too much to ask the gatekeepers of the Java docs you are aggegating to do the same. Are you suggesting someone write an app to parse the HTML and spit out XML?

Oh, and...
You forgot to mention that AJAX is for people who are too stupid to learn Flash. Haaaaar!

Oh, and...
The guys who are to stupuid to learn what AJAX is or what FLASH is... and to know how to make a diference beetween those 2.... like you, should shut up. If you think that you can do with flash what you can do with java or PHP.. think again... please think hard.. very hard....