Designing an effective API is essential for library developers as it is the lens through which clients will judge its usability and benefits, as well as the main friction point when the library evolves. Despite its importance, defining the boundaries of an API is a challenging task, mainly due to the diverse mechanisms provided by programming languages that have non-trivial interplays. In this paper, we present a novel conceptual framework designed to assist library maintainers in understanding the interactions allowed by their APIs via the use of syntactic usage models. These customizable models enable library maintainers to improve their design ahead of release, reducing friction during evolution. The complementary syntactic usage footprints and coverage scores, inferred from client code using the API (e.g., documentation samples, tests, third-party clients), enable developers to understand in-the-wild uses of their APIs and to reflect on the adequacy of their tests and documentation. We implement these models for Java libraries in a new tool UCov and demonstrate its capabilities on three libraries exhibiting diverse styles of interaction: jsoup, commons-cli, and spark. Our exploratory case study shows that UCov provides valuable information regarding API design and fine-grained analysis of client code to identify under-tested and under-documented library code.

翻译：设计高效的API对库开发者至关重要，因为它是客户端判断库可用性和效益的窗口，也是库演化时的主要摩擦点。尽管其重要性不言而喻，但定义API的边界仍是一项极具挑战性的任务，这主要归因于编程语言提供的多种机制之间存在复杂的相互作用。本文提出一种新颖的概念框架，旨在通过使用句法使用模型来帮助库维护者理解其API所允许的交互行为。这些可定制化模型使库维护者能够在发布前改进API设计，从而减少演化过程中的摩擦。从使用API的客户端代码（如文档示例、测试用例、第三方客户端）中推断出的互补性句法使用足迹和覆盖率分数，使开发者能够理解API在现实场景中的使用情况，并反思其测试和文档的充分性。我们针对Java库在新型工具UCov中实现了这些模型，并在三个展现不同交互风格的库（jsoup、commons-cli和spark）上展示了其能力。探索性案例研究表明，UCov能够提供关于API设计的宝贵信息，并对客户端代码进行细粒度分析，以识别测试不足和文档缺失的库代码。