Be the first to like this
These are the early draft slides for my EclipseCon 2009 talk, "You probably should be reading this..." - Getting people to read your JavaDocs with eMoose.
An unfortunate reality of Java development is that we rarely have the time to thoroughly read the documentation of every method we invoke, or even to read it at all. Most of the time we can safely rely on the signature, as the detailed specifications are consistent with our expectations. In some cases, however, the JavaDocs also convey unexpected “directives”, such as rules that callers must follow or caveats of which they should be aware. If these go unnoticed, the consequences could be severe.
The first part of this talk will present examples of surprisingly hazardous situations from the standard library and suggest practices that documentation authors can follow to help readers notice directives in the text. With standard tools, however, there is no way for these authors to attract callers to read the text in the first place. The second part of this talk will describe how our eMoose framework can help make developers aware of directives in invoked methods. Authors can explicitly tag directives in the JavaDocs and distribute libraries of tags to clients. Our Eclipse plug-in continuously monitors the Java editor and attempts to match all call targets against these tags. If a match is found the call is decorated, offering a cue that the documentation may be worth investigating.
eMoose if freely available from http://emoose.cs.cmu.edu