A Methodology for Intentional Specification and User-Centered Documentation of Object-Oriented APIs

Abstract

The ideal companion to any application programming interface (API) is its documentation, which can take various forms, such as API reference documentation, user guides, and tutorials. One of the essential resources for learning APIs, commonly found in many types of API documentation, is code examples that demonstrate common API usage. However, writing and maintaining effective API usage examples is often a demanding and repetitive process for API developers. This is because API users ideally expect these examples to be simple, standalone, and linear. This PhD research addresses this challenge by providing an approach to assist API developers in producing and maintaining effective API usage examples. The approach also aims to support the development of code examples that align with API users' expectations, thereby promoting API learnability. Additionally, this research proposes a method to assess coverage of API code examples. The proposed approach provides API developers with a dedicated API description language that enables them to concisely describe intended APIs. This API description is then utilised to report code example coverage both textually and visually. The evaluation conducted in this research demonstrates that the proposed techniques can reduce the effort required to write and maintain API code examples by minimising repetition in example code and generating linear code. A controlled user study further shows that linear code examples are easier to comprehend and are preferred by API users. The findings also indicate that the proposed code example coverage tool and its accompanying API description language can simplify the process of describing intended APIs for API developers by providing features that facilitate formal and concise API specifications.