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.