Jadeite: improving API documentation using usage information

ABSTRACT

Jadeite is a new Javadoc-like API documentation system that takes advantage of multiple users' aggregate experience to reduce difficulties that programmers have learning new APIs. Previous studies have shown that programmers often guessed that certain classes or methods should exist, and looked for these in the API. Jadeite's "placeholders" let users add new "pretend" classes or methods that are displayed in the actual API documentation, and can be annotated with the appropriate APIs to use instead. Since studies showed that programmers had difficulty finding the right classes from long lists in documentation, Jadeite takes advantage of usage statistics to display commonly used classes more prominently. Programmers had difficulty finding the right helper objects and discovering how to instantiate objects, so Jadeite uses a large corpus of sample code to automatically identify the most common ways to construct an instance of any given class.

REFERENCES

• 1: Joshua Bloch, Effective Java programming language guide, Sun Microsystems, Inc., Mountain View, CA, 2001
• 2: Clarke, S. 2004. Measuring API Usability. Dr. Dobbs Journal, Windows / .NET Supplement. May 2004. 6--9.
• 3: Krzysztof Cwalina , Brad Abrams, Framework design guidelines: conventions, idioms, and patterns for reusable .net libraries, Addison-Wesley Professional, 2005
• 4: Brian Ellis , Jeffrey Stylos , Brad Myers, The Factory Pattern in API Design: A Usability Evaluation, Proceedings of the 29th international conference on Software Engineering, p.302-312, May 20-26, 2007 [doi>10.1109/ICSE.2007.85]
• 5: Andrew Forward , Timothy C. Lethbridge, The relevance of software documentation, tools and technologies: a survey, Proceedings of the 2002 ACM symposium on Document engineering, November 08-09, 2002, McLean, Virginia, USA [doi>10.1145/585058.585065]
• 6: Douglas Kramer, API documentation from source code comments: a case study of Javadoc, Proceedings of the 17th annual international conference on Computer documentation, p.147-153, September 12-14, 1999, New Orleans, Louisiana, United States [doi>10.1145/318372.318577]
• 7: Jeffrey Stylos , Steven Clarke, Usability Implications of Requiring Parameters in Objects' Constructors, Proceedings of the 29th international conference on Software Engineering, p.529-539, May 20-26, 2007 [doi>10.1109/ICSE.2007.92]
• 8: Jeffrey Stylos , Brad A. Myers, The implications of method placement on API learnability, Proceedings of the 16th ACM SIGSOFT International Symposium on Foundations of software engineering, November 09-14, 2008, Atlanta, Georgia [doi>10.1145/1453101.1453117]
• 9: Jeffrey Stylos , Brad A. Myers, Mica: A Web-Search Tool for Finding API Components and Examples, Proceedings of the Visual Languages and Human-Centric Computing, p.195-202, September 04-08, 2006 [doi>10.1109/VLHCC.2006.32]

INDEX TERMS

Primary Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
      D.2.7 Distribution, Maintenance, and Enhancement
          Subjects: Documentation

General Terms:
Documentation

Keywords:
APIs, documentation, javadoc