Not really a tool, but I've been working on annotating important things in the JavaDocs for Swing (and several other APIs). Too many methods contain surprises like "don't call this if you want a refresh, call X instead". I use a tool that I built for my PhD to access that kind of info (it highlights calls in the source code to methods that have those sort of things).
IMHO, the JavaDocs for swing are difficult to use because they combine information that is meant for people using an object and people subclassing existing classes.
