The online technical Q&A site Stack Overflow (SO) is popular among developers to support their coding and diverse development needs. To address shortcomings in API official documentation resources, several research works have thus focused on augmenting official API documentation with insights (e.g., code examples) from SO. The techniques propose to add code examples/insights about APIs into its official documentation. Recently, surveys of software developers find that developers in SO consider the combination of code examples and reviews about APIs as a form of API documentation, and that they consider such a combination to be more useful than official API documentation when the official resources can be incomplete, ambiguous, incorrect, and outdated. Reviews are opinionated sentences with positive/negative sentiments. However, we are aware of no previous research that attempts to automatically produce API documentation from SO by considering both API code examples and reviews. In this article, we present two novel algorithms that can be used to automatically produce API documentation from SO by combining code examples and reviews towards those examples. The first algorithm is called statistical documentation, which shows the distribution of positivity and negativity around the code examples of an API using different metrics (e.g., star ratings). The second algorithm is called concept-based documentation, which clusters similar and conceptually relevant usage scenarios. An API usage scenario contains a code example, a textual description of the underlying task addressed by the code example, and the reviews (i.e., opinions with positive and negative sentiments) from other developers towards the code example. We deployed the algorithms in Opiner, a web-based platform to aggregate information about APIs from online forums. We evaluated the algorithms by mining all Java JSON-based posts in SO and by conducting three user studies based on produced documentation from the posts. The first study is a survey, where we asked the participants to compare our proposed algorithms against a Javadoc-syle documentation format (called as Type-based documentation in Opiner). The participants were asked to compare along four development scenarios (e.g., selection, documentation). The participants preferred our proposed two algorithms over type-based documentation. In our second user study, we asked the participants to complete four coding tasks using Opiner and the API official and informal documentation resources. The participants were more effective and accurate while using Opiner. In a subsequent survey, more than 80% of participants asked the Opiner documentation platform to be integrated into the formal API documentation to complement and improve the API official documentation.

中文翻译：

---

来自技术问答网站的自动 API 使用场景文档

在线技术问答网站 Stack Overflow (SO) 在开发人员中很受欢迎，以支持他们的编码和多样化的开发需求。为了解决 API 官方文档资源中的缺陷，一些研究工作因此集中在使用来自 SO 的见解（例如代码示例）来扩充官方 API 文档。这些技术建议将有关 API 的代码示例/见解添加到其官方文档中。最近，对软件开发者的调查发现，SO 中的开发者将代码示例和 API 评论的组合视为 API 文档的一种形式，并且在官方资源可能不完整的情况下，他们认为这种组合比官方 API 文档更有用、模棱两可、不正确和过时。评论是带有积极/消极情绪的自以为是的句子。然而，我们知道以前没有研究试图通过考虑 API 代码示例和评论来从 SO 自动生成 API 文档。在本文中，我们介绍了两种新颖的算法，通过结合代码示例和对这些示例的评论，它们可用于从 SO 自动生成 API 文档。第一种算法称为统计文档，它使用不同的指标（例如星级）显示围绕 API 代码示例的积极性和消极性分布。第二种算法称为基于概念的文档，它将相似且概念相关的使用场景聚集在一起。API 使用场景包含代码示例、代码示例解决的底层任务的文本描述以及评论（即，其他开发人员对代码示例的正面和负面情绪的意见。我们将算法部署在 Opiner 中，这是一个基于 Web 的平台，用于从在线论坛汇总有关 API 的信息。我们通过在 SO 中挖掘所有基于 Java JSON 的帖子并根据帖子中生成的文档进行三项用户研究来评估算法。第一项研究是一项调查，我们要求参与者将我们提出的算法与 Javadoc 样式文档格式（在 Opiner 中称为基于类型的文档）进行比较。参与者被要求比较四个开发方案（例如，选择、文档）。与基于类型的文档相比，参与者更喜欢我们提出的两种算法。在我们的第二次用户研究中，我们要求参与者使用 Opiner 和 API 官方和非正式文档资源完成四项编码任务。参与者在使用 Opiner 时更加有效和准确。在随后的调查中，超过 80% 的参与者要求将 Opiner 文档平台集成到正式的 API 文档中，以补充和改进 API 官方文档。