What should developers be aware of? An empirical study on the directives of API documentation

@article{Martin2011WhatSD,
  title={What should developers be aware of? An empirical study on the directives of API documentation},
  author={Monperrus Martin and Michael Eichberg and Elif Tekes and Mira Mezini},
  journal={Empirical Software Engineering},
  year={2011},
  volume={17},
  pages={703 - 737},
  url={https://api.semanticscholar.org/CorpusID:8174618}
}
This paper presents the design and the results of an empirical study on the directives of API documentation of object-oriented libraries, and proposes and extensively discusses a taxonomy of 23 kinds of API directives.
[PDF] Semantic Reader

90 Citations

An observational study on API usage constraints and their documentation

This paper implemented and validated strategies to automatically detect four types of usage constraints in existing APIs and observed that some of the constraint types are frequent and that for three types, they are not documented in general.

A Systematic Approach to Extract Knowledge Types in API Reference Documentation: A Survey

The main idea of this paper is to extract knowledge types in API Reference Documentation and to study the gap between information seekers & information providers.

Patterns of Knowledge in API Reference Documentation

The taxonomy and patterns of knowledge presented can be used to help practitioners evaluate the content of their API documentation, better organize their documentation, and limit the amount of low-value content.

Documentation Reuse: Hot or Not? An Empirical Study

This paper performs an empirical study of duplications in JavaDoc documentation on a corpus of seven famous Java APIs and makes a proposal for a simple but efficient automatic reuse mechanism.

Inferring API Usage Patterns and Constraints : a Holistic Approach

A novel approach is presented, to automatically identify third-party library usage patterns, of libraries that are commonly used together, to help developers to discover reuse opportunities, and pick complementary libraries that may be relevant for their projects.

Exploring the Correspondence Between Types of Documentation for Application Programming Interfaces

This thesis explores the relationship between instructional and API reference documentation of three libraries on the topics: regular expressions, URL connectivity and file input/output in two programming languages, Java and Python and proposes techniques to assist automation of each reuse pattern to reduce documentation creation efforts, inform documentation design and promote information consistency.

Analyzing APIs Documentation and Code to Detect Directive Defects

This paper proposes an automated approach to detect defects of API documents by leveraging techniques from program comprehension and natural language processing, and focuses on the directives of the API documents which are related to parameter constraints and exception throwing declarations.

The impact of API evolution on API consumers and how this can be affected by API producers and language designers

This thesis investigates the relationship between API consumers, API producers, and language designers to understand how each has a role to play in reducing the burden of dealing with API evolution.

DRONE: A Tool to Detect and Repair Directive Defects in Java APIs Documentation

DRONE, a tool that can automatically detect the directive defects in APIs documents and recommend repair solutions to fix them, is presented, which focuses on four defect types related to parameter usage constraints.

An Empirical Study on API Parameter Rules

An empirical study investigates what types of parameter rules there are, and how these rules distribute inside documents and source files, and reveals the challenges for automating parameter rule extraction.
...

55 References

Mining subclassing directives to improve framework reuse

This paper presents an approach to documentation of object-oriented white-box frameworks which mines from client code four different kinds of documentation items, which it calls subclassing directives.

API documentation from source code comments: a case study of Javadoc

This paper describes in a general way the process we went through to determine the goals, principles, audience, content and style for writing comments in source code for the Java platform at the Javaโ€ฆ

What Makes APIs Hard to Learn? The Answers of Developers

A study of the obstacles professional developers at Microsoft faced when learning how to use APIs showed that resources for learning an API were critically important, and shed light on three API learning obstacles.

Improving API documentation usability with knowledge pushing

This work presents a lab study that demonstrates the directive awareness problem in traditional documentation use and the potential benefits of an Eclipse plug-in named eMoose, which decorates method invocations whose targets have associated directives.

An Empirical Study on Evolution of API Documentation

Based on the methodology, a quantitative study on API documentation evolution of five widely used real-world libraries is conducted, and the results reveal various valuable findings that allow programmers and library developers to better understandAPI documentation evolution.

Inferring Resource Specifications from Natural Language API Documentation

An approach that infers resource specifications from API documentation with relatively high precisions, recalls, and F-scores is proposed, and the usefulness of inferred specifications through detecting bugs in open source projects is evaluated.

A case study of API redesign for improved usability

A usability evaluation of the proposed changes to the API suggests that the user-centered design process evolved in redesigning SAP's BRFplus was successful in helping to create an API that significantly improved users' productivity and better matches the different users' needs.

Increasing awareness of delocalized information to facilitate API usage

By overlaying visual cues on particular function calls in the source code, developers can make developers aware of the presence of directives in the documentation of the call targets by listing them explicitly when this text is read, which can increase the prospects of the directives actually being consumed.

The Factory Pattern in API Design: A Usability Evaluation

A user study comparing the usability of the factory pattern and constructors in API designs found highly significant results indicating that factories are detrimental to API usability in several varied situations.

Improving API documentation using API usage information

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