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. Abstract: 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

1. Uri Dekel Institute for Software Research Carnegie Mellon University EclipseCon 2009 http://emoose.cs.cmu.edu You probably should be reading this… Getting people to read your Javadocs with eMoose Early version (03/20/2009) Final slides will change

7. Specifications example (Java 1.4) Intro Problem Tips eMoose

8. Directive example (Java 1.6): Intro Problem Tips eMoose

10. The problem… Intro Problem Tips eMoose

11. Directives can be lost within the text… Intro Problem Tips eMoose

12. Most code fragments make many calls Intro Problem Tips eMoose

13. Impractical to read every target Intro Problem Tips eMoose

15. Directives can hide in unexpected locations… Intro Problem Tips eMoose

16. Newly added calls may also hide directives Intro Problem Tips eMoose

17. Some methods can behave in unexpected ways Intro Problem Tips eMoose

18. There may be a surprise in an overridden version… Intro Problem Tips eMoose

19. What you can do as a documentation writer…. Intro Problem Tips eMoose

20. What you can do… Make it easier for readers of your documentation to become aware of directives within it! Intro Problem Tips eMoose

26. What you can’t do… Signal to clients that they may benefit from the documentation of your method Intro Problem Tips eMoose

27. eMoose Intro Problem Tips eMoose

34. JavaDoc hover in polymorphism Intro Problem Tips eMoose

38. Populating the Knowledge Space Intro Problem Tips eMoose

39. All active //TODO comments in the code Intro Problem Tips eMoose

46. Homepage: http://emoose.cs.cmu.edu Update site: http://emoose.cs.cmu.edu/dist/updatesite http://emoose.cs.cmu.edu/dist/updatesite_mac Try eMoose today ! Intro Problem Tips eMoose

47. Backup

51. eMoose study results