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