Software development is nowadays largely the process of integrating existing features and reusing them by writing client code interfacing to one or more Application Programming Interfaces (API). Thus, APIs are the key to software reuse: they allow programmers beyond the original developers to use a certain component or service. Although the official API documentation often is a sufficient source of information when a developer takes a new API into use, online discussion forums – such as Stack Overflow – often provide more explanatory descriptions of specific API usages relevant to the developers. However, while the answers given at Stack Overflow may be syntactically correct, such crowdsourced knowledge is not without problems. While it is often notably faster and easier to find relevant information for a specific API from the Internet than from the official documentation, the crowdsourced API knowledge is scattered around the Internet. Also, the answers given in the discussion forums are usually not updated whenever the official documentation is updated, making the answers obsolete with time.
Without proper tool support, creating and maintaining API documentation is a demanding task. Whenever the source code for the API is updated, the corresponding documentation needs to be updated as well. When code updates are done frequently, it is not uncommon that the necessary documentation updates are forgotten, or inadequate. On the other hand, when developers take a new API into use for their software, finding the correct interface for a specific problem might be demanding because of the size of the documentation. Easily finding the correct resources in an API is therefore of importance.
All the things mentioned above point towards the same need: tools to create and maintain API documentation. With such tools, the expectation is that creating accurate API documentation is notably easier and faster, and this helps API users produce better software more quickly.
In a paper we published in the 44th Euromicro Conference on Software Engineering and Advanced Applications in 2018, we presented a systematic mapping study on the research on approaches for API documentation generation. We identified 36 studies on API documentation generation tools and approaches and analyzed and categorized these in a variety of ways. Among other things, we provided an overview of what kind of tools have been developed, what kind of documentation they generate, and what sources the documentation approaches require. Below is a truncated table from the published paper on the different outputs generated by the identified approaches, including how many of these that contribute to the different types of outputs.
| Documentation Output | Count | Description |
| Examples & Templates | 11 | Produces examples of how to use the API or basic structures for using the API |
| NL Documentation | 10 | Produces or augments the natural language description in the API documentation |
| Specifications & Rules | 9 | Produces specifications (e.g. formal specifications) and usage rules |
| Visual & Navigational Enhancement | 9 | Visual representation of API or simplified browsing in the documentation |
| Recommendations & Identifications | 5 | Recommendations of different kinds (e.g. documentation in need of attention, which class to use), identifications of e.g. incorrect descriptions |
The topic of API documentation has been addressed in the scientific community quite actively since the beginning of the millennium. The number of publications on a yearly basis is illustrated in the figure below. Given the number of publications each year, it is clear that there is a need for improving the process of both generating and maintaining API documentation.
The results presented in our paper can be of use in academia by providing a comprehensive overview of what approaches that have been developed for API documentation generation and maintenance. The results can also be of use for industry looking for approaches to assist in their API documentation process.