Context: Application Programming Interface (API) code examples are an essential knowledge resource for learning APIs. However, a few user studies have explored how the structural characteristics of the source code in code examples impact their comprehensibility and reusability.

One of the most effective resources for learning application programming interfaces (APIs) is code examples. The shortage of such examples can pose a significant learning obstacle for API users. API users desire simple, understandable, self-contained examples that are easy to reuse in their applications. However, writing and maintaining code examples that meet the preferences of API users can be a tedious and repetitive activity for API developers. To address this issue, we present a new approach that aims to ease the writing and maintenance of code examples for API developers, while also improving learnability and comprehension for API users. The approach automatically synthesises linear and more comprehensible API code examples from less repetitive and more maintainable versions by inlining reusable utility methods. We implement this approach in a prototype for the Java programming language. We also evaluate its usefulness in terms of conciseness on a dataset of 600 API code examples extracted from nine open-source Java libraries. The results are encouraging and show that the proposed approach can reduce code repetition and bring a decrease of up to 37% in the lines of code of the evaluated API code examples.

Code examples are essential resources for learning application programming interfaces (APIs). The shortage of such examples can be a major learning obstacle for API users. Writing and maintaining effective API usage examples can also be an effort-intensive and repetitive process for API developers because API users ideally want such examples to be simple, standalone, and linear. To address these challenges, several approaches have been proposed to automatically extract API code examples from various resources and embed them into official API documents; however, little emphasis has been placed on addressing the underlying issue directly and helping API developers write and maintain API usage examples. In this paper, we present a new approach for automatically synthesising linear code examples from less repetitive versions by in-lining reusable utility methods. The proposed approach aims to benefit API developers in terms of productivity and maintainability, as well as API users in terms of API learnability and comprehension. We have implemented the proposed approach in a prototype for the Java programming language, which we also discuss in this paper.