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}
}
Application Programming Interfaces (API) are exposed to developers in order to reuse software libraries. API directives are natural-language statements in API documentation that make developers aware of constraints and guidelines related to the usage of an API. This paper presents the design and the results of an empirical study on the directives of API documentation of object-oriented libraries. Its main contribution is to propose and extensively discuss a taxonomy of 23 kinds of API… 
An observational study on API usage constraints and their documentation
TLDR
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
TLDR
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
TLDR
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
TLDR
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
TLDR
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
TLDR
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
TLDR
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
TLDR
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
TLDR
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
TLDR
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.
...
...

References

SHOWING 1-10 OF 56 REFERENCES
Mining subclassing directives to improve framework reuse
TLDR
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
Improving API documentation usability with knowledge pushing
  • Uri Dekel, J. Herbsleb
  • Computer Science
    2009 IEEE 31st International Conference on Software Engineering
  • 2009
TLDR
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
TLDR
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.
What Makes APIs Hard to Learn? Answers from Developers
TLDR
The article focuses on the obstacles to learning an API and concludes that as APIs keep growing larger, developers will need to learn a proportionally smaller fraction of the whole.
Inferring Resource Specifications from Natural Language API Documentation
TLDR
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
TLDR
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
TLDR
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.
Improving software API usability through text analysis: A case study
  • Robert B. Watson
  • Computer Science
    2009 IEEE International Professional Communication Conference
  • 2009
TLDR
This case study describes how the application of technical communication skills and tools helped improve the usability and clarity of a new application program interface (API) by performing a text analysis of the API elements.
The Factory Pattern in API Design: A Usability Evaluation
TLDR
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.
...
...