API文档分析 张静宣 大连理工大学 2017年11月3日

自我介绍 张静宣(Jingxuan Zhang) 大连理工大学软件学院 软件工程理论与技术研究所 Email: jingxuanzhang@mail.dlut.edu.cn 主页: http://oscar-lab.org/people/~jxzhang/ 2008-2012：大连理工大学本科 2012-2014：大连理工大学硕士，导师：江贺 2014.5-8 ：新加坡管理大学研究助理，导师：David Lo 2014-现在 ：大连理工大学博士，导师：江贺 研究方向：软件数据分析，软件仓库挖掘 研究内容：bug报告自动摘要，App功能推荐，API文档分析

汇报内容 背景介绍 1 API文档内容分析 2 API文档信息增强 3 API文档参考推荐 4 5 总结

API文档-帮助开发者学习API的正确使用 挑战 API文档-帮助开发者学习API的正确使用

API文档的分类 API 规范 教程 博客 论坛 Maalej W, Robillard M P. Patterns of knowledge in API reference documentation, IEEE Transactions on Software Engineering, 2013, 39(9): 1264-1282.

API文档的内容 既包含有自然语言的描述，又包含少量代码样例。同时自然语言的描述有可能也包含代码元素。 Zhong H, Su Z. Detecting API documentation errors, International Conference on Object Oriented Programming Systems Languages & Applications (OOPSLA). ACM, 2013:803-816.

API文档的质量 研究者对API文档的质量做了问卷调查。他们邀请在IBM和微软的开发者参与调研API学习的障碍和API文档失效的原因。 知识不明确 信息（代码）缺失 冗长且碎片化 内容错误 尝试自动发现并理解文档的关键知识 尝试自动填充缺失的关键信息（代码） 尝试自动切分文档并推荐相关片段 尝试自动发现文档的错误并推荐修改 Uddin G, Robillard M P. How API Documentation Fails[J]. IEEE Software, 2015, 32(4):68-75. Robillard M P. What Makes APIs Hard to Learn? Answers from Developers[J]. IEEE Software, 2009, 26(6):27-34.

目标 API文档 内容分析 1 API文档 信息增强 2 API文档 参考推荐 3 知识不明确 信息（代码）缺失 冗长且碎片化

汇报内容 背景介绍 1 API文档内容分析 2 API文档信息增强 3 API文档参考推荐 4 5 总结

API文档的知识 已有研究者对API文档包含的知识进行了人工分析，发现了12中知识类型以及他们的出现模式。 Maalej W, Robillard M P. Patterns of knowledge in API reference documentation, IEEE Transactions on Software Engineering, 2013, 39(9): 1264-1282.

API directive自动发现 定义：API directive是正确调用API所必须遵守的约束和限制 挑战： API directive对不同粒度API（比如类，接口，函数，字段等）的约束的描述很不一样。很难构建统一的模型来很好的度量他们的属性和特征。 API directive在API文档中所占的比例极少（小于5%），导致API directive不容易被自动的发现。

API directive自动发现 解决方案: 带不平衡类别处理的文本分类方法

API directive自动发现 我们提出的方法是否超过对比方法？ 我们的方法平均超过对比方法20%。 我们的方法是一个更好的方法。

API directive自动发现 自动的识别高亮directive是否对开发者有利？ 自动识别和高亮directive对开发者有利。

汇报内容 背景介绍 1 API文档内容分析 2 API文档信息增强 3 API文档参考推荐 4 5 总结

API文档信息增强 问题： 研究目标：自动的为API文档（API规范）添加高质量的代码样例及其使用场景。 只有11%的Java API规范和6%的Android API规范包含代码样例，远远不能满足开发者的需要。 API规范的代码样例没有与之对应的使用场景，无法快速理解该代码样例的功能。 研究目标：自动的为API文档（API规范）添加高质量的代码样例及其使用场景。 代码来源：Stack Overflow问答对 Kim J, Lee S, Hwang S W, et al. Enriching Documents with Examples: A Corpus Mining Approach, ACM Transactions on Information Systems, 2013, 31(1):157-160.

API文档信息增强 解决方案: 基于群智的代码样例填充方法。

API文档信息增强 方法步骤： 度量指标： 我们方法增强的API文档能否提高开发者效率？ 邀请21个参与者，设计问卷调查调研他们的编程背景。根据他们的学习编程的时间和经验，将他们分成技能相等的3组。 给每个参与者提供一个实验教程，介绍整个实验的相关概念，实验流程和注意事项等。确保实验前每个参与者都了解了整个流程。 使用屏幕录像工具来全程记录参与者的编程行为。对于三组参与者，第三组是实验组，前两组是控制组。实验组提供使用我们的方法得到的增强后的API文档。控制组分别提供原始API文档和对比方法得到的增强后的文档。 我们设计了一系列实际的Java编程任务，根据Java教程设计了一系列编程任务，让每组参与者根据手头分配的文档完成编程任务。 每个参与者根据手头分配的文档顺序完成上述编程任务。 通过分析每个参与者的录像，得到结果进行对比。 度量指标： 完成编程任务的数量 完成编程任务的时间

API文档信息增强 我们方法增强的API文档能否提高开发者效率？ 我们的人员分组策略有效。

汇报内容 背景介绍 1 API文档内容分析 2 API文档信息增强 3 API文档参考推荐 4 5 总结

API文档参考推荐 问题： 研究目标：自动的发现并推荐解释某个API的文档片段。 单个API文档冗长，不能快速定位想要的内容。 IR GMR FITSEA Input Unfamiliar APIs Output Relevant API tutorial fragments explaining unfamiliar APIs Method Information Retrieval Text Classification Details Cosine similarities are calculated between fragments and API specifications. Twenty features are defined to measure linguistic and structural characteristics between fragments and APIs. It introduces some new sources to extend APIs. Besides, co-occurrence APIs are proposed. Drawbacks Precision is low Different corpora require their corpus-specific annotated data. The effectiveness of supervised approaches depends on the features. 研究目标：自动的发现并推荐解释某个API的文档片段。

API文档参考推荐 现有工作的不足：监督模型需要大量人工标注构建训练集，同时预测效果依赖于提取的特征，在应用中并不准确。 目标：提出一种无监督模型。 相关性识别阶段: 发现API与文档片段的相关性。 片段推荐阶段: 为用户输入的不熟悉的API推荐文档解释片段。

API文档参考推荐 我们提出的无监督方法效果如何？ 作为一种无监督方法，我们提 出的方法超过现有监督方法。 Corpus Tutorial Precision (%) Recall (%) F-Measure (%) FRAPT FITSEA GMR IR McGill Corpus JodaTime 85.19 69.00 58.82 73.00 76.67 74.17 50.00 80.70 70.24 54.05 Math Library 84.78 67.89 52.00 67.00 73.58 72.70 49.06 65.00 78.79 61.53 50.49 66.00 Col. Official 62.03 55.74 62.69 30.00 87.50 48.62 31.79 94.00 72.59 48.10 42.18 45.00 Col. Jenkov 61.19 90.44 82.14 33.00 97.62 85.17 58.97 88.00 75.23 68.66 48.00 Smack 77.94 83.38 70.00 74.00 94.64 88.33 93.33 85.48 83.90 80.00 61.00 Android Corpus Graphics 49.21 50.42 45.60 35.80 75.61 42.52 44.50 67.44 59.62 43.73 45.04 46.77 Resources 65.22 75.83 55.00 40.32 66.67 66.17 21.11 55.56 65.93 66.80 30.51 46.73 Data 71.43 56.52 19.29 33.33 14.76 44.00 62.50 54.17 16.72 37.93 Text 57.58 36.19 37.21 76.00 48.33 22.22 57.14 65.52 39.56 45.07 作为一种无监督方法，我们提 出的方法超过现有监督方法。 考虑到无监督方法的优点，用 我们提出的方法来发现解释 API的文档片段是个很好的选 择。

汇报内容 背景介绍 1 API文档内容分析 2 API文档信息增强 3 API文档参考推荐 4 5 总结

总结 作为学习API的最重要的资源，API文档的质量并 不理想。 对API文档进行分析，进而提高API文档的质量是 当前研究热点问题。

谢谢！ 张静宣 大连理工大学 2017年11月3日