What I think is the best thing you can do for API documentation is to let users comment the 'official' documents. This is now possible with a AJAX API viewer available at http://www.jdocs.com/.

But this is not the only cool thing about this API browser: it contains all the Java API's you need in your daily Java-live: JDK, hibernate, spring, log4j, ehcache, apache commons, all other apache libraries, groovy graisls, eclipse, lucene.... It's all in there, one consistene interfaces, with comments and free.

Really cool I think!