API文档分析 1 汇报内容汇报内容 2 3 1 5 4 背景介绍 API文档内容分析 API文档信息增强 API文档参考推荐 总结 2 API文档 帮助开发者学习API的正确使用 API和API文档 挑战 3 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 4 既包含有自然语言的描述 又包含少量代码样例 同时自然 语言的描述有可能也包含代码元素 Zhong H Su Z Detecting API documentation errors International Conference on Object Oriented Programming Systems Languages Applications OOPSLA ACM 2013 803 816 API文档的内容 5 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 尝试自动发现并理解文档的关键知识 尝试自动填充缺失的关键信息 代码 尝试自动切分文档并推荐相关片段 尝试自动发现文档的错误并推荐修改 6 API文档 内容分析 1 API文档 信息增强 2 API文档 参考推荐 3 目标 知识不明确信息 代码 缺失冗长且碎片化 7 汇报内容汇报内容 2 3 1 5 4 背景介绍 API文档内容分析 API文档信息增强 API文档参考推荐 总结 8 API文档的知识 Maalej W Robillard M P Patterns of knowledge in API reference documentation IEEE Transactions on Software Engineering 2013 39 9 1264 1282 已有研究者对API文档包含的知识进行了人工分析 发现了12 中知识类型以及他们的出现模式 9 API directive自动发现 定义 API directive是正确调用API所必须遵守的约束和限 制 目标 自动的识别和高亮API文档中的directive 提醒开发者 挑战 1 API directive对不同粒度 API 比如类 接口 函数 字段等 的约束的描述很不一 样 很难构建统一的模型来很 好的度量他们的属性和特征 2 API directive在API文档中 所占的比例极少 小于5 导致API directive不容易 被自动的发现 10 API directive自动发现 解决方案 带不平衡类别处理的文本分类方法 11 API directive自动发现 我们提出的方法是否超过对比方法 1 我们的方法平均超过对比方法20 2 我们的方法是一个更好的方法 12 API directive自动发现 自动的识别高亮directive是否对开发者有利 1 自动识别和高亮directive对开发者有利 13 汇报内容汇报内容 2 3 1 5 4 背景介绍 API文档内容分析 API文档信息增强 API文档参考推荐 总结 14 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 15 API文档信息增强 解决方案 基于群智的代码样例填充方法 16 API文档信息增强 我们方法增强的API文档能否提高开发者效率 方法步骤 1 邀请21个参与者 设计问卷调查调研他们的编程背景 根据他们的学习编程的时 间和经验 将他们分成技能相等的3组 2 给每个参与者提供一个实验教程 介绍整个实验的相关概念 实验流程和注意事项 等 确保实验前每个参与者都了解了整个流程 3 使用屏幕录像工具来全程记录参与者的编程行为 对于三组参与者 第三组是实验 组 前两组是控制组 实验组提供使用我们的方法得到的增强后的API文档 控制 组分别提供原始API文档和对比方法得到的增强后的文档 4 我们设计了一系列实际的Java编程任务 根据Java教程设计了一系列编程任务 让每组参与者根据手头分配的文档完成编程任务 5 每个参与者根据手头分配的文档顺序完成上述编程任务 6 通过分析每个参与者的录像 得到结果进行对比 度量指标 1 完成编程任务的数量 2 完成编程任务的时间 17 API文档信息增强 我们方法增强的API文档能否提高开发者效率 1 我们的人员分组策略有效 2 利用我们方法增强的API文档 可以提高开发者的编程效率 18 汇报内容汇报内容 2 3 1 5 4 背景介绍 API文档内容分析 API文档信息增强 API文档参考推荐 总结 19 API文档参考推荐 问题 单个API文档冗长 不能快速定位想要的内容 解释某个API的文档片段分布在文档的各个部分 并不是某个API出现 该文档就一定是解释这个API的 研究目标 自动的发现并推荐解释某个API的文档片 段 IRGMRFITSEA InputUnfamiliar APIs OutputRelevant API tutorial fragments explaining unfamiliar APIs MethodInformation RetrievalText ClassificationText 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 DrawbacksPrecision is low Different corpora require their corpus specific annotated data The effectiveness of supervised approaches depends on the features 20 API文档参考推荐 相关性识别阶段 发 现API与文档片段的相 关性 片段推荐阶段 为用 户输入的不熟悉的API 推荐文档解释片段 现有工作的不足 监督模型需要大量人工标注构建训练 集 同时预测效果依赖于提取的特征 在应用中并不准确 目标 提出一种无监督模型 21 API文档参考推荐 我们提出的无监督方法效果如何 CorpusTutorialPrecision Recall F Measure FRAPT FITSEAGMRIRFRAPT FITSEAGMRIRFRAPT FITSEAGMRIR McGill Corpus JodaTime85 19 69 00 58 82 73 00 76 67 74 17 50 00 73 00 80 70 70 24 54 05 73 00 Math Library84 78 67 89 52 00 67 00 73 58 72 70 49 06 65 00 78 79 61 53 50 49 66 00 Col Official62 03 55 74 62 69 30 00 87 50 48 62 31 79 94 00 72 59 48 10 42 18 45 00 Col Jenkov61 19 90 44 82 14 33 00 97 62 85 17 58 97 88 00 75 23 85 17 68 66 48 00 Smack77 94 83 38 70 00 74 00 94 64 88 33 93 33 52 00 85 48 83 90 80 00 61 00 Android Corpus Graphics49 21 50 42 45 60 35 80 75 61 42 52 44 50 67 44 59 62 43 73 45 04 46 77 Resources65 22 75 83 55 00 40 32 66 67 66 17 21 11 55 56 65 93 66 80 30 51 46 73 Data71 43 56 52 19 29 33 33 55 56 52 00 14 76 44 00 62 50 54 17 16 72 37 93 Text57 58 36 19 66 67 37 21 76 00 48 33 22 22 57 14 65 52 39 56 33 33 45 07 1 作为一种无监督方法 我们提 出的方法超过现有监督方法 2 考虑到无监督方法的优点 用 我们提出的方法来发现解释 API的文档片段是个很好的选 择 22 汇报内容汇报内容 2 3 1 5 4 背景介绍 API文档内容分析 API文档信息增强 API文档参考推荐 总结 23 总结 作为学习API的最重要的资源 API文档的质量并 不理想 对API文档进行分析 进而提高API文档的质量是 当前研究热点问题 我们分别介绍了API文档内容分析 信息增强和 参考推荐方面的工作 但这些研究还无法完全消除API文档的全部问题 还有很多研究问题 24 Thank you 25