What should developers be aware of? An empirical study on the directives of API documentation

Abstract

Application Programming Interfaces (API) are exposed to developers in order to reuse software libraries. API directives are natural-language statements in API documentation that make developers aware of constraints and guidelines related to the usage of an API. This paper presents the design and the results of an empirical study on the directives of API documentation of object-oriented libraries. Its main contribution is to propose and extensively discuss a taxonomy of 23 kinds of API directives.

Analyzing APIs Documentation and Code to Detect Directive Defects

“…The packages parsed by our prototype contain around 0.5 million lines of code (LoC) 9 and 16379 Javadoc tags in total. The details are summarized in Table II.…”

“…The inputs expExtractor are the statement sequence of the source code as an AST representation and the depth of the call hierarchy. First the algorithm iterates the statements in m. If ) If the statement itself is a composite block, we recursively go through the internal statements of the block, and extract the corresponding exception information (line [7][8][9][10]. If the statement invokes another method call, and m's argument(s) is(are) passed onto the callee method n, we will use the recursion with parameters -the statement body of the callee method as the parameter, together with the depth value decreased by 1 (line [12][13][14][15].…”

“…Among these, we hypothesize that statements on function signatures (i.e., related to parameter types and values) and exceptions provide the most crucial information for users during programming. In [9], such statements are defined as directives, which are the main focus of our work. Particularly, we limit our attention to method parameter usage constraints and relevant exception specifications.…”

“…http://stackoverflow.com/questions/2967303/ inconsistency-in-java-util-concurrent-future, posted by Mark Peters on June 03, 2010 all API documentation directives (43.7%) [9]. Indeed, all of the aforementioned illustrative examples are directives within this category.…”

What makes a good code example?: A study of programming Q&A in StackOverflow

“…Nontrivial and infrequent knowledge about how to use elements of an API could be hidden under tons of API documentation text. Two studies defined different types of these hidden elements (called directives) [8,18]. Dekel also built a tool integrated to an IDE to present these important elements to developers while they are using the API and showed that it improved the outcome of documentation reading for their study subjects [9].…”