Live API Documentation Siddharth Subramanian, Laura Inozemtseva, and Reid Holmes School of Computer Science University of Waterloo Waterloo, ON, Canada s23subra,lminozem,[email protected] ABSTRACT main issues is that the documentation is often out of date. Application Programming Interfaces (APIs) provide power- Recent work has confirmed the popular belief that writing ful abstraction mechanisms that enable complex functional- documentation and keeping it up to date is very difficult [8, ity to be used by client programs. However, this abstraction 9]; consequently, developers ignore the documentation that does not come for free: understanding how to use an API can does exist and declare that \code is king" [17]. be difficult. While API documentation can help, it is often As a result of this situation, developers often turn to online insufficient on its own. Online sites like Stack Overflow and resources such as Stack Overflow. Parnin et al. have previ- Github Gists have grown to fill the gap between traditional ously studied online resources and have found that they do API documentation and more example-based resources. Un- a good job of covering APIs [15]. In fact, they found that fortunately, these two important classes of documentation 87% of Android classes were referenced in Stack Overflow an- are independent. swers. Unfortunately, there are rarely links between online In this paper we describe an iterative, deductive method resources and official API documentation: the official doc- of linking source code examples to API documentation. We umentation does not link to the examples that could help also present an implementation of this method, called Baker, developers, and the examples rarely link to the documenta- that is highly precise (0.97) and supports both Java and tion. JavaScript. Baker can be used to enhance traditional API Previous work has tried to identify source code references documentation with up-to-date source code examples; it can within non-code resources (e.g., [2, 14,9, 16]). Detect- also be used to incorporate links to the API documentation ing these references is a first step toward linking them to into the code snippets that use the API. the relevant API documentation. Unfortunately, these ap- proaches have several limitations. Some systems explicitly ignored external references, meaning that the target sys- Categories and Subject Descriptors tem for an analyzed document must be specified [9]. Others D.2.6 [Software Engineering]: Programming Environments only returned partially qualified names, which are insuffi- cient for documentation linking [16]. Our initial investiga- tion found that this approach could work for a subset of Java General Terms programs [18]. However, none of the previous approaches Languages, Experimentation worked for dynamically-typed languages. Our paper extends previous work in this area by using a Keywords constraint-based technique to uniquely identify fine-grained type references, method calls, and field references in source Source code examples, source code search, documentation code snippets with high precision. We demonstrate the gen- erality of the approach by providing implementations for 1. INTRODUCTION both typed (Java) and dynamic (JavaScript) languages. We Using third-party libraries can greatly reduce the effort also evaluate the ability of the approach to correctly link required to develop a new system. Unfortunately, under- code to documentation. standing how to use these libraries correctly can be diffi- More specifically, the contributions of this paper are as cult. While the application programming interface (API) follows: documentation can be a valuable means of understanding the library, it can be insufficient on its own. One of the • A constraint-based, iterative approach for determining the fully qualified names of code elements in source code snippets. This approach works with both stati- cally and dynamically typed languages. Permission to make digital or hard copies of all or part of this work for personal or classroom use is granted without fee provided that copies are • A prototype tool that implements this approach and not made or distributed for profit or commercial advantage and that copies uses the results to automatically create bidirectional bear this notice and the full citation on the first page. To copy otherwise, to links between documentation and source code exam- republish, to post on servers or to redistribute to lists, requires prior specific ples by marking up HTML using a web browser exten- permission and/or a fee. ICSE ’14, May 31–June 7, 2014, Hyderabad, India sion. Copyright 14 ACM 978-1-4503-2756-5/14/05 ...$15.00. Section2 presents a scenario that motivates our approach 1 $("#addphoto").on(’click’, and demonstrates the kinds of links it can identify. The ap- 2 function() { useGetPicture();} proach and our implementation of it are explained in detail 3 ); in Sections3 and4. Section5 then presents our evaluation of 4 function useGetPicture() { 5 var cameraOptions = { ... }; Baker. The documentation linking prototype is described in 6 navigator.camera.getPicture(onCameraSuccess, Section6, followed by discussion in Section7. Related work 7 onCameraError, cameraOptions); is described in Section8; Section9 concludes the paper. 8 } 9 function onCameraSuccess(imageData) { 10 var image = document.getElementById(".."); 11 image.src = "data:image/jpeg" + imageData; 12 } 2. SCENARIO 13 function onCameraError(message) { Consider the Java code snippet shown in Figure1. This 14 alert("Failed: " + message); snippet (pertaining to a library called GWT) was posted to 15 } Stack Overflow to assist a developer who did not understand how to manipulate the state of History objects. The figure contains a number of bolded elements. These are the types Figure 2: A JavaScript code snippet containing Cor- and methods that our tool, Baker, can uniquely link to the dova, JQuery and JavaScript DOM API usage. Each API; i.e., the elements for which it can determine a fully- of the bolded elements can be linked back to the rel- qualified name. With this information we can automatically evant API documentation. augment the HTML version of the official API documenta- 3. APPROACH tion for History by dynamically injecting the code example into the web page. We can also inject the links to the official Identifying API elements in code snippets requires the API into the Stack Overflow post; these two additions to the ability to parse these snippets. This is more difficult than documentation would make it easier for developers to learn parsing full files because code snippets can be ambiguous. how to use this class. Dagenais and Robillard highlighted four kinds of ambiguity that can hamper the identification of elements [9]; two of these were specific to the plain-text analysis they were per- 1 public FirstPanel() { forming, while the other two were more generally relevant. 2 History.addHistoryListener(this); These two were declaration ambiguity and external reference 3 String token = History.getToken(); ambiguity. if (token.length() == 0) { 4 Declaration Ambiguity. Snippets are, by definition, in- 5 History.newItem(INIT_STATE); 6 } else { complete fragments of code. That is, snippets might not be 7 History.fireCurrentHistoryState(); embedded in methods or classes, they may reference fields 8 } whose declaration is not included, and their identifiers are 9 .. rest of code largely unqualified. In source code examples this is often 10 } exacerbated by authors ending lines with `. ' or using code comments to describe parts of the functionality that are elided. Figure 1: A Java code snippet representing a Java API usage. Baker can associate each of the bolded External Reference Ambiguity. Source code examples terms with a fully qualified name; this information frequently refer to external identifiers; for example, Java can be used to include the code example in the API snippets frequently reference types from the JDK. While documentation. a previous study [9] dealt with external references by elid- ing everything that was not from a pre-specified library, we designed Baker to handle these kinds of ambiguities. We ac- Next, consider the JavaScript snippet in Figure2, where complished this by using an oracle: a large database contain- a developer is trying to make a web app that can take a ing information about the code elements in popular APIs. photo and inject it into an element in an HTML docu- When Baker encounters an ambiguous code element, such as ment. This example interacts with the JavaScript DOM the History class in Figure1, it uses the oracle to identify (getElementById), takes a photo using the Cordova pro- the possible types of the code element. In this case, there ject (getPicture), and uses JQuery to detect when the are 58 History classes in the oracle, but by using informa- the photo should be taken ($ and on). For each of these tion from other parts of the code snippet, we can identify method references Baker can can identify the API that it is which of the 58 is the correct one. Section4 will present from. more information about how the oracle is constructed, what The code snippets in Figures1 and2 were both submit- it contains, and how much of a problem ambiguity really is. ted as the correct solution to problems developers posted on Stack Overflow. Since Stack Overflow posts are ranked, 3.1 Deductive Linking and accepted answers are known to have solved a real prob- Baker handles declaration ambiguity and external refer- lem, Stack Overflow is a good source of high quality code ence ambiguity through a process we call deductive linking. snippets that demonstrate the correct usage of many APIs. At a high level, it generates an incomplete abstract syntax Increasing the integration between these examples and the tree (AST) for the code snippet being analyzed, then uses official API documentation will make documentation main- information from the oracle to deduce facts about the AST. tenance easier and increase the visibility and accessibility of We perform this deduction step iteratively since each phase the official API documentation within source code examples.