【转载】迈向按需的开发文档生成:开源软件项目API文档生成



  • 文章转载自 CodeWisdom,原文地址:https://mp.weixin.qq.com/s/EPbHHTY4n1LNdoHaqwuQqA

    软件项目开发文档缺失或陈旧是困扰开发者、影响开发效率和质量的一个大问题。针对这一问题的传统解决方案是通过各种信息检索技术搜索各种软件开发文档、制品和代码来获取所需要的信息,但其效果十分有限。为此,软件维护与演化领域的研究者提出了按需的开发文档(On-demand Developer Documentation,简称OD3)[1]的思想。其设想如下图所示:在开发者给定的查询及上下文信息的基础上,OD3引擎动态地从各种相关的文档、代码及其他制品中抽取相关信息并动态生成易读、易理解的开发文档。

    0_1538324793711_f8fb1a4d-487d-4e18-82df-34637cb4b9a4-image.png

    针对这一设想,相关研究者组织了动态软件开发文档研讨会(International Workshop on Dynamic Software Documentation),并在今年与ICSME 2018共同主办的第三届会议(https://dysdoc.github.io/dysdoc3/index.html) 上第一次举办了软件文档生成挑战赛(Software Documentation Generation Challenge,简称DocGen)。本次比赛要求针对开源的Apache POI项目(面向微软Office的Java API项目,http://poi.apache.org),动态生成针对每个类的API文档。POI项目有着广泛的应用,在StackOverflow等开发论坛上也有大量的讨论,但是其API文档非常不健全。

    复旦大学CodeWisdom团队参加了本次挑战赛,并获得了全体观众投票产生的唯一优胜奖。相关同学包括刘名威、刘阳、王翀、谢文凯、王拓、邢双双、白雪芳、张晓欣、汪昕、赵逸凡、张峰逸等。

    研究方法
    我们在前期积累的API知识图谱及相关的语义检索技术基础上,针对比赛要求开发了一个开源软件项目API文档生成系统OpenAPIDocGen。我们针对比赛指定的POI项目构建了一个API知识图谱,其中既包含基本的API元素定义结构也包含与通用概念的链接。在此基础上实现了针对StackOverflow上相关的讨论文本内容的分析识别,可以抽取与指定API相关的使用场景或问题解决相关的讨论内容。除此之外,我们也集成了注释信息抽取、样例代码抽取、基于规则和深度学习的注释生成等技术。最终实现的自动文档生成工具可以针对给定的POI类(给定完整类名)动态生成一个包含类描述、相关API和概念推荐、API知识图谱展示、API使用提示、API样例代码等丰富内容的API文档。

    目前,我们在CodeWisdom平台上部署了OpenAPIDocGen,在线访问地址为:http://bigcode.fudan.edu.cn/OpenAPIDocGen/。 在该系统中输入完整的POI项目类名(例如org.apache.poi.xslf.usermodel.XMLSlideShow)后即可动态生成文档。

    文档内容

    • API类基本信息 包括继承层次和功能解释

    0_1538324916972_eadd5c63-20f9-4f78-b724-12a64f70e4f2-image.png

    • 相关API及概念推荐 包括相关类与概念

    0_1538324952580_5f000267-2b34-4eb1-bf91-58daefacefc1-image.png

    • 概念图谱 与当前类相关的API元素及概念图谱
      可以设置不同类型实体和概念的显示并逐层点击展开。

    0_1538324967577_49e5fd3f-fc0a-43da-bcfa-ac66d1f4b4f1-image.png

    • 使用提示 当前类的使用说明
      通过从StackOverflow相关讨论中抽取相关的句子得到。

    0_1538324984304_3a5b3f8d-97d8-4594-8309-5830ad72a758-image.png

    • 相关讨论 当前API类的相关讨论
      通过从StackOverflow相关讨论中抽取相关的讨论得到。

    0_1538324996649_1369748c-8e63-447e-b671-9f6984403401-image.png

    • 类方法 当前API类的方法信息
      包括声明信息、方法描述及相关API元素和概念推荐。

    0_1538325013681_df7de519-af9f-4cfc-83e1-bc49e2c4d904-image.png

    • 类详细 息 API方法详细信息
      包括相关提示语句和讨论推荐等。

    0_1538325023905_daf77e0d-6a34-4adf-b2ed-06177a8cd4e1-image.png

    引用文献:
    [1] Martin P. Robillard, Andrian Marcus, Christoph Treude, Gabriele Bavota, Oscar Chaparro, Neil A. Ernst, Marco Aurélio Gerosa, Michael W. Godfrey, Michele Lanza, Mario Linares Vásquez, Gail C. Murphy, Laura Moreno, David C. Shepherd, Edmund Wong: On-demand Developer Documentation. ICSME 2017: 479-483


Log in to reply
 

Popular Topics

|

Looks like your connection to SCC was lost, please wait while we try to reconnect.