API Document Quality for Resolving Deprecated APIs

Using deprecated APIs often results in security vulnerability or performance degradation. Thus, invocations to deprecated APIs should be immediately replaced by alternative APIs. To resolve deprecated APIs, most developers rely on API documents provided by service API libraries. However, the documents often do not have sufficient information. This makes many deprecated API usages remain unresolved, which leads programs to vulnerable states. This paper reports a result of studying document quality for deprecated APIs. We first collected 260 deprecated APIs of eight Java libraries as well as the corresponding API documents. These documents were manually investigated to figure out whether it provides alternative APIs, rationales, or examples. Then, we examined 2,126 API usages in 249 client applications and figured out whether those were resolved in the subsequent versions. This study revealed that 1) 3.6 APIs was deprecated and 3.6 deprecated APIs are removed from the library a month on average, 2) only 61% of API documents provided alternative APIs while rationale and examples were rarely documented, and 3) 62% of deprecate API usages in client applications were resolved if the corresponding API documents provided alternative APIs while 49% were resolved when the documents provided no alternative APIs. Based on these results, we draw future directions to encourage resolving deprecated APIs.