Improving API Documentation for Java-like Languages
The Javadoc paradigm for displaying API documentation to users is quite popular, with similar variants existing for many mainstream languages. However, two user interface design properties of Javadoc may reduce its utility when displaying documentation for APIs that make use of inheritance and parametric polymorphism. First, Javadoc does not show a flattened view of all members of a class or interface, but rather only those defined directly in the type. Second, and as a consequence, any methods whose types contain type parameters of a superclass will always be shown in the context of the superclass. That is, if the method C.m returns type T, subclasses of C will always see this parent signature, even if they instantiate T to a concrete type such as Integer. We show that this situation arises often in some libraries, and present the results of a study that measures the usability consequences of these two Javadoc design decisions. Our results show that a user interface that shows instantiated type parameters for members is preferred over one that presents type parameters in the Javadoc style.
Cite this item
Dubochet, G., & Malayeri, D. (2010). Improving API Documentation for Java-like Languages. Evaluation and Usability of Programming Languages and Tools, Reno, Nevada, USA. https://infoscience.epfl.ch/handle/20.500.14299/53487
Click Copy to copy the citation, or select the text manually.
plateau10-dubochet.pdf
openaccess
505.04 KB
Adobe PDF
fbf89bacacfc3d733ed4b2ee88c78290