Synthesizing API Usage Examples

The idea of the paper is mining source code in order to find common patters, in order to obtain examples that can be used for documentation purposes. So instead of relying on that one entry you find on StackOverflow, you can learn from many users of a given API.

One thing the authors found is that there might be multiple allowed uses for an API call. Those are clustered based on data flow, and subsequently generalized these to obtain a pattern that is more abstract. From this abstract pattern, a code example is generated.

What I like about this work is that is solving a very real problem, I would not even dare to estimate the time that is lost every year by developers browsing API docs or trying to get examples from StackOverflow to work. At least I have spent many hours that way, and I didn’t enjoy them. Furthermore the examples can be used 1) to warn developers they are using an API in an unusual way and 2) creating extensive code completion that adds and entire example within existing code.

The authors furthermore performed a extensive study with 150 students, in which they compared existing documentation and hand-written examples with their extracted examples. This evaluation showed that the students rated the extracted examples readable and important. One of the limitations the authors state is the lack of ‘storytelling’ features that human examples have, where the rationale behind the code is given, either in text or in comments added to the code. Despite this limitations, still, this is very useful work, in my opinion.

More details in the paper.