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. Prototypical Examples "@param obj must be a Number or a Date.", 35 "The Cert-Path specif ied must be of a type that is supported by the validation algorithm, otherwise an InvalidAlgorithmParameterException will be thrown.", 36 "@param obj [typed as 32 in JDK's Statement.execute(sql, autoGeneratedKeys) 33 in JDK's ServerSocket.ServerSocket(port, backlog, bindAddr) 34 in JDK's CallableStatement.registerOutParameter(parameterIndex, sqlType, scale) 35 in JDK's DateFormat.format(obj, toAppendTo, fieldPosition) 36 in JDK's CertPathValidator.validate(certPath, params)
Monperrus et al. REF conducted an empirical study on the directives, and 23 kinds of directives were developed and discussed.
What should developers be aware of? An empirical study on the directives of API documentation
Empirical Software Engineering
Empirical Software Engineering
Computer Science