Seeing the Forest for The Trees: Sifting Through Javadoc and Code

Darin Wright, Michael Wallick, Uri Dekel

Eclipse IDE And Languages - Java · Long - curated
Wednesday, 10:10, 50 minutes | Room 209/210

7
·
8
·
9
·
10
·
11
·
12
·
13
·
14
·
15
·
16
·
17
·
18

There's a bewildering amount of code in the Eclipse ecosystem. As a consumer, how can you find what you're looking for? As a producer how can you draw attention to what's important. This series of three short talks showcases tips and tricks for navigating code in the SDK with Plug-in Spy and more, things you never knew you could do with Javadoc, and how to draw attention to important aspects of your API with a tool called eMoose.

10 Things You Never Knew You Could do with JavaDoc

Method Detail

javaDocTalk

TalkAbstract.Information javaDocTalk(TalkAbstract.Speaker speaker,
                                     java.util.ArrayList<TalkAbstract.Attendee> audience)

The Eclipse Javadoc viewer includes a powerful HTML renderer and viewer. This allows traditional Javadoc comments to include simple decorations such as Bold and Italics. However with a little bit of creativity and work, more advanced javadoc comments are possible. For example, external images can be embedded to illustrate how methods work.

A developer may consider linking to Bugzilla to help users track and report issues found with an under-development project, or give an e-mail address for the same purpose.

In this talk I will show approximately 10 different ways to create interactive, dynamic and generally interesting Javadoc comments; discuss the limitations of the HTML browser; and invite the Eclipse Community to come up with more new ways to maximize Javadoc usage.

Parameters:
speaker - TalkAbstract.SpeakerThe person who is going to deliver this talk
audience - TalkAbstract.Attendee those attending this talk hoping to learn new ways of using JavaDoc.
Returns:
A new way of looking at and creating Javadoc comments

Extra Information
The entire Javadoc of this abstract (with working links). You can download an Eclipse Ready version of this abstract. Or see screen shots fo the Javadoc browser.

"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

Darin is a senior software developer with IBM Rational Software. He is an Eclipse committer, lead for the Eclipse Debug Platform, Java Debugger, API Tools, PDE, and and a member of the Eclipse Architecture Council. Darin has presented talks and tutorials at EclipseCon. For the better part of the last thirteen years, Darin has been working on IDE's such as Eclipse, VA/Micro Edition, and ENVY/Smalltalk. In a previous software development life, Darin was an audio software developer supporting virtual reality productions at the Banff Centre for the arts.

Michael received his BS in Computer Science (with Honors) from the University of Central Florida in 2001. He was awarded a Masters and Ph.D. in Computer Science from the University of Wisconsin-Madison in 2003 and 2007 respectively, where he worked on software for automatic video editing and automatic organization of large collections of digital photographs. In 2004 he was named as a Microsoft Research Graduate Fellow. He joined the Operations Planning Software Group (and Ensemble Project) at the NASA Jet Propulsion Laboratory in 2007, where he is leading the development of a mission data search interface for the Mars Science Laboratory rover, and future missions.

Michael currently lives in Montrose, CA with his wife Christine and their son Ethan.

Uri is a Ph.D. candidate of Software Engineering at Carnegie Mellon University's School of Computer Science. His research is concerned with human aspects of software development, including program understanding, collaborative work, and documentation usability. He spends too much of his research time developing software, and for the past few years has been working on the eMoose memory aid for software developers (http://emoose.cs.cmu.edu). Prior to his doctoral studies he developed software at Intel and at IBM Research. He also taught courses on software development at the Israel Institute of Technology, where he received his M.Sc. and B.Sc. degrees in Computer Science.

Gold sponsors

IBM Corporation

Windriver logo

JBoss

Sun Microsystems

SOPERA

BLU AGE

BIRT Exchange by Actuate

Silver sponsors

Innovations Software Technology

Google

Genuitec

Instantiations

itemis

EclipseSource

Innovent Solutions

SAP Business Objects

Hardware Sponsor

Cisco

Lanyard Sponsor

Intel logo



report a problem with this page