开题报告JavaScript在API文档生成.docVIP

本科毕业设计开题报告 （201届） 选题的背景与意义 1.1研究开发的目的 随着软件工程的规模越来越大，参与项目的人数也越来越多，因此非常需要有API文档来描述各个模块的功能，以让团队内的成员无需关心其它人的编码细节就能协调开发，减少沟通成本。 API文档可以让作者自己书写，但毫无疑问书写文档的时间是非常长的，而且现代软件项目的需求经常改变，这就意味着每次修改需求都要重新修改源码和对应的文档，其维护的成本是相当大的。因此现实很少有人会花额外时间来编辑API文档。 如果将文档直接以注释的方式写进代码里，这样源码和文档总是出现在一起，修改的时候可以一并修改，这样就能大大减少维护文档的时间成本了。同时也方便其他人在阅读源码时通过注释来更直观地理解功能。 文档生成工具可以提取源码中的注释，并最后生成一个可供人直接阅读的API文档。使用一些工具来生成API文档自然可以节约额外的文档书写时间，也可以在源码被修改后重新生成文档，而不需要每次都手写文档。因此，开发一个优秀的文档生成工具是非常有必要的。 传统的API文档都是一个类似word的本地数据文件，它确实完成了API文档所应该拥有的功能。但在 web2.0 时代，如果能让更多人通过网页参与API文档内容的讨论，则可以帮助作者修正错误，更帮助其他读者理解。同时还能让来自不同地区的读者在网站上共同学习、共同进步。因此生成的文档可以让读者可以就某个API进行评论。 在线API文档也方便读者浏览文档，读者不需要安装额外的软件，只需一个浏览器即可直接打开文档。 1.2国内外研究发展现状 目前主流的编程语言都有相应的文档生成工具。比如Java语言可以使用javadoc来生成文档，生成的文档非常精确， C#有开源的NDoc[1] 项目。 目前国外最有名的JavaScript文档生成工具为jsdoc toolkit[2]，它的工作原理是在强制作者在代码中书写一些标记，然后jsdoc文档会分析这些标记来构建文档，并确保最后生成的文档是正确的。虽然使用这个方式比较容易理解和使用，但由于它只分析这些标记，而忽略源码本身，很多可以从源码中得到的信息必须在标记中重新写明，所以让文档书写的工作量倍增。此外，它还具有以下缺点： 1. 只有命令行模式，新用户不容易上手。 2. 由于是国外的项目，中文容易出现乱码。 3. 生成的文档比较简单，信息量少。 因此它不是完美的解决方案。 目前最有名的在线API文档系统为MSDN，MSDN 库为使用 Microsoft? 工具、产品、技术和服务的开发人员提供必不可少的信息资源。MSDN 库包含操作方法和参考文档、示例代码、技术文章和其他内容。但 MSDN 仅针对指定平台才能使用，而且MSDN是不开源的，无法被其他用户使用[3]。  研究开发的基本内容、目标，拟解决的主要问题或技术关键 2.1研究开发的内容 本研究是针对JavaScript 语言的文档生成。 程序数据流图如图2-1所示。 图2-1 数据流图 文档分析 根据指定的源码解析得到文档的原始数据。分析算法是整个研究的重点课题。 文档分析内主要经过词法分析[3]、注释分析、语法分析[4]、注释语义分析、合成文档这几个步骤。词法分析和注释分析同时进行，它的目标是提取源码的注释和代码。词法分析可以输出得到全部标识符。语法分析时根据词法分析得到标识符构建语法树。语法树包含了所有的源码信息。在得到了源码的结构和注释信息后，即可开始注释语义分析，它一边遍历语法树，一边分析每个注释的含义，并得出一个完整的变量集合，变量集合包含了所有被成功解析的注释的信息。最后分析变量集合提取最终的文档信息。最终的文档数据以XML格式保存。 展示网站 为了方便用户在线浏览文档，必须提供一个网站形式的文档系统。这个网站可以读取XML格式的文档并以网页形式展示。同时网站还允许用户登录以每个API接口进行讨论。 用户操作界面 为了用户可以方便地使用软件来生成，软件必须提供一个图形操作界面。操作界面的主要功能就是让用户选择需要生成文档的源文件位置，然后即可运行得到最终的文档。 2.2研究开发的基本目标 该软件主要分三个部分： 软件主体。本程序目标用户为源码作者，这些用户可以通过这个软件进行文档生成操作，同时软件也会向它们报告解析错误。 文档网站。网站用于展示文档，同时网站允许使用不同的模板风格，方便用户自定义网站。 可以为最终用户提供联机使用帮助，包括本系统的说明信息、使用方法和步骤以及版权信息和联系方式等。 2.3拟解决的主要问题或技术关键 准确地分析 文档生成工具应该自动分析注释上下文，自动决定注释含义，以保证文档的正确性。因为利用好编译原理的相关内容是分析的关键。 友好的用户界面 用户的操作应该尽量简单。如果出