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 M. 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… Expand
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. Expand
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. Expand
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. Expand
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. Expand
Exploring the Correspondence Between Types of Documentation for Application Programming Interfaces
Documentation of software programming languages and their APIs exist in many forms, whether as official reference documentation, user-created blog posts or other textual and visual mediums. PriorExpand
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. Expand
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. Expand
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. Expand
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. Expand
Automatic Detection and Repair Recommendation of Directive Defects in Java API Documentation
TLDR
DRONE (Detect and Repair of dOcumentatioN dEfects), a framework to automatically detect and repair defects from API documents by leveraging techniques from program analysis, natural language processing, and constraint solving, is proposed. Expand
...
1
2
3
4
5
...

References

SHOWING 1-10 OF 54 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. Expand
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 JavaExpand
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. Expand
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. Expand
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. Expand
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. Expand
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. Expand
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. Expand
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. Expand
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. Expand
...
1
2
3
4
5
...