摘要: 应用程序编程接口（API）提供对用于构建和集成应用程序软件复杂功能的访问。开发人员可以使用这些API提供的复杂功能，而无需修改或理解底层的实现细节。因此，开发人员倾向于在现有框架和库中重用API以促进开发过程。但是API通常很复杂且难以学习，因为它们可能包含数百个不同级别的元素（包、类和方法），并且包含复杂的依赖项。因此，各种类型的API文档提供了API的使用说明来帮助开发人员学习API，例如API规范，API教程，API众智文档，Wiki和博客。
然而目前尚不清楚不同类型的API文档在帮助开发人员学习API的难易程度上是否存在差异。本文中，我们以API官方教程和API众智文档为例，分析对比不同类型的API文档。API官方教程通常由API的设计者组织书写，API众智文档则来源于社交媒体，比如Stack Overflow。尽管这两种文档的来源不同，但是它们都提供了描述性语言和代码段来展示如何使用API。因此，我们的目标是分析比较API官方教程和API众智文档在帮助开发人员学习API的难易程度上是否有差异以及差异程度。
为了实现这个目标，我们在Java API文档和Android API文档上进行实验。我们从Oracle网站收集了1,062个Java官方教程，从Stack Overflow上收集了462,154个Java帖子。同时，我们从Android SDK中收集了181个Android官方教程，从Stack Overflow上收集了393,812个Android帖子。从Stack Overflow上收集的帖子经过问答对匹配，将问题和它的最佳答案进行组合构成API众智文档。然后我们从三个方面对API文档进行分析：API的覆盖率、API的关注度以及API文档格式。API的覆盖率能够分析开发人员能否通过参考API文档来了解API的使用。API的关注度能够说明API教程上的API和开发人员使用的API是否有差异。API文档格式揭示了API文档风格是否会影响开发人员学习使用API。因此，我们提出三个研究问题：
1.API官方教程和API众智文档对API的覆盖率分别是多大？
我们使用Recodoc工具将两种类型的API文档中的code-like terms链接到某个特定的API元素上（包、类或方法）。对于Java API，我们链接到Java SE 7 API，对于Android API，我们连接到Android library 7 API。基于每个API元素出现的频率，我们能够分析API文档对API元素的覆盖率。
2.API官方教程和API众智文档对API的关注度是否一致？
我们将API的排序或API排序百分比作为API关注度的一个指标。首先，我们根据每个API元素出现的频率对这些API降序排序，然后分别选取两种文档中top 15的API进行分析。另外我们也选取包含子类相对多的API包和API类，计算它们在不同文档中的排序百分比的差异值。若API元素的差异值超过50%，说明API官方教程和API众智文档对该API的关注度出现不匹配现象。
3.API官方教程和API众智文档在对API的解释上是否有差异，差异程度有多大？
我们首先通过调查问卷的形式分析API文档中的哪些特征有利于开发人员学习API。根据调查结果，我们使用Wilcoxon秩和检验来区分不同文档的特征是否有差异。同时，我们使用Spearman秩相关系数分析不同特征之间是否存在相关性，进而给API文档的设计者提供一些建议，使得API文档更能满足开发人员的需求。
经过分析，我们发现API众智文档对API的覆盖率高于API官方教程，因此开发人员可以参考API众智文档学习如何使用API。而且被API官方教程覆盖的大部分API都能够在API众智文档中找到相关解释，因此我们认为API众智文档可以作为API官方教程的补充来帮助开发人员学习API。我们还发现API的关注度在这两种文档中存在不一致现象。也就是说，API设计者和开发人员可能专注于不同的API，尤其对于细粒度的API元素，比如API方法。这可能导致开发人员找不到关于某个API的解释信息，降低他们学习API的效率。另外，我们发现长文本和链接有助于开发人员详细深入理解API的设计和使用。API官方教程有利于开发人员在同一页面搜索和学习API。API众智文档中的代码块有助于开发人员使用某些API完成特定的编程任务。这些特征能够被集成到新的API文档中，使得API文档能够更好地帮助开发人员学习使用API。