Invitation to weigh in on the future of javadoc
For some time I've been peddling this theory that one of the greatest barriers to Swing adoption is our monolithic API documentation (javadoc). I'm a personal fan of javadoc and rely on it for solving a large percentage of my programming questions, but you could say I know where to look, and that, at least in the Swing case, over the years my brain has learned to block out that 80% which isn't actually needed to construct a GUI. Picking on JButton - I only really need 3 or 4 of the 300+ methods and the ones I need arn't even listed in the Method Summary table because they are actually defined in its superclass, AbstractButton. But I know that, so it's not a problem. But what about the poor soul embarking on his or her first Swing client? And of course this problem isn't limited to Swing, but afflicts many of the larger APIs in J2SE (JDBC, XML, etc). Sometimes bigness creeps up on you.
Javadoc's structure really hasn't changed at all in the last 10 years because it serves quite well as the Java platform's API reference. The questions we are trying to answer for JSR260 are should it evolve? and how? So I entreat you to take this short(!) survey and tell us what you think:
Your answers will make a difference.