A Systematic Mapping Study on API Documentation Generation Approaches

Abstract

Background: Application Programming Interfaces (APIs) are key to software reuse. Software developers can link functionality and behaviour found in other software with their own software by taking an API into use. However, figuring out how an API works is usually demanding, and may require that the developers spend a notable amount of time familiarizing themselves with the API. Good API documentation is of key importance to simplify this task. Objective: To present a comprehensive, unbiased overview of the state-of-the-art on tools and approaches for API documentation generation. Method: A systematic mapping study on published tools and approaches that can be used for generating API documentation, or for assisting in the API documentation process. Results: 36 studies on API documentation generation tools and approaches analyzed and categorized in a variety of ways. Among other things, the paper presents an overview of what kind of tools have been developed, what kind of documentation they generate, and what sources the documentation approaches require. Conclusion: Out of the identified approaches, many contribute to API documentation in the areas of natural language documentation and code examples and templates. Many of the approaches contribute to ease API users' understanding and learning of the API, but also to the maintenance and generation of API documentation. Most of the approaches are automatic, simplifying the API documentation generation notably, under the assumption that relevant sources for the generation are available. Most of the API documentation approaches are evaluated either by exercise of the approach followed by analysis of the results, or by empirical evaluation methods.