JavaScript在线API文档生成.docx

JavaScript在线API文档生成.docx

《JavaScript在线API文档生成.docx》由会员分享，可在线阅读，更多相关《JavaScript在线API文档生成.docx（28页珍藏版）》请在冰豆网上搜索。

JavaScript在线API文档生成

本科毕业设计说明书（论文）

（2012届）

论文题目JavaScript在线API文档生成

摘要

JavaScript是目前最流行的脚本语言。

它起初是为网页提供交互能力而设计的一门基于对象的普通脚本语言。

但随着一些Web新标准的出现和一些像Nodejs之类的JavaScript客户端宿主程序的流行，JavaScript的用途也越来越广，一个JavaScript的项目也随之变大。

因此现在对JavaScript项目的API文档的需求也迅速膨胀。

为了将作者从手动书写API文档的繁琐过程中解脱出来，必须要有一个强大的工具能够提取代码中的注释，并自动生成一份完整的API文档。

传统的一些JavaScript文档生成项目，比如jsdoc，只能生成比较简单的文档，无法很好地满足现在的新需求。

本文研究对JavaScript源码中的注释进行解析，然后提取有用的API信息，并最后生成一个完整的文档页面供读者阅读。

解析过程充分考虑了JavaScript语言的灵活特性，让JavaScript源码作者可以快速地为自己的代码生成对应的文档。

同时为了方便用户进行文档生成操作，使用C#开发一个WinForm软件。

生成的文档是一个普通的网页，用户可以自定义文档界面模板。

生成的文档可以放在ASP.NET服务器上直接运行。

读者可以在线阅读文档，并在文档的任何一页添加评论。

关键词：

JavaScript,API,文档生成,WinForm

Abstract

JavaScriptisthemostpopularscriptlanguagenowadays,whichisdesignedasasimpleobject-basedscriptlanguagetoprovidetheabilityofinteractionforwebpagesatfirst.ButalongwiththeappearanceofnewwebstandardsandthepopularityofsomeJavaScriptclientslikeNodejs,theusageofJavaScriptincreasessoonandtheJavaScriptprojectsbecomemorecomplex,whichleadstonewrequirementofJavaScriptdocumentationaswell.

ToavoidauthorswritingAPIDocumentwordbyword,thereshouldbeapowerfultooltoexportanAPIdocumentfromthesourcecodeautomatically.ThetraditionalrelatedprojectssuchasJsdocshowtheirshortcomingwhenmeetingnewrequirements.ThisarticlefocusesonanalyzingsourcecodeofJavaScriptandthengeneratingafullAPIdocument.TheanalyzingprogramisfitforJavaScript,whichcansavealotoftimeforJavaScriptauthors.

ThisarticlealsotalksaboutdevelopingaprogramofWinFormtomakeiteasiertooperate.Ontheotherhand,userscancustomthetemplatesofdocumentifneeded.ThegeneratedAPIdocumentcanrunonASP.NETserverdirectly.Readerscanviewthedocumentonlineandleavetheircommentsonanypage.

Keywords：

JavaScript,API,DocumentGenerator,WinForm

目录

摘要I

AbstractI

第一章绪论3

1.1研究开发的目的3

1.2国内外研究发展现状4

1.3研究开发的基本目标4

1.4本文的组织结构5

第二章方法与技术6

2.1软件运行环境6

2.1.1客户端环境要求6

2.1.2服务器环境要求6

2.2WinForm简介6

2.3ASP.NET简介7

2.4AJAX简介7

2.5编译原理8

2.6系统构架:

B/S构架8

2.7主要开发语言9

2.8开发工具9

2.8.1VisualStudio20109

2.8.2Firebug9

第三章需求分析10

3.1软件主体10

3.1.1用例图10

3.1.2新建和保存项目10

3.1.3编辑项目10

3.1.4编译项目11

3.2生成的文档界面11

3.3用于在线可评论的文档12

3.4文档调试工具12

第四章系统设计实现13

4.1文档解析核心13

4.1.1数据流图13

4.1.2类图14

4.1.3相关的实体类14

4.1.4DocProject类的实现15

4.1.5DocParser类的实现16

4.1.6JavaCommentParser类的实现17

4.1.7JavaScript语法树构建器的实现17

4.1.8DocAstVistor类的实现18

4.1.9DocMerger类的实现18

4.1.10DocGenerator类的实现19

4.2软件主体19

4.2.1界面布局19

4.2.2项目操作20

4.2.3软件实现20

4.3文档页面23

4.4在线文档评论24

4.5文档调试工具25

第五章系统测试27

5.1单元测试27

5.2系统功能测试27

第六章总结28

6.1完成的工作28

6.2下一步工作28

参考文献29

致谢31

附录32

附录1毕业设计文献综述32

附件2毕业设计开题报告32

附件3毕业设计外文翻译（中文译文与外文原文）32

图目录

图11文档注释3

图21Firebug运行界面9

图31软件主体用例图10

图41数据流图13

图42类图14

图43DocData的字段15

图44软件主体的布局19

图45软件主体运行界面21

图46编辑项目21

图47设置项目属性22

图48控制台22

图49文档界面23

图410评论框24

图411文档调试工具25

表目录

表4-1接口设计24

表4-2数据库设计25

第一章绪论

1.1研究开发的目的

随着软件工程的规模越来越大，参与项目的人数也越来越多，因此非常需要有API文档来描述各个模块的功能，以让团队内的成员无需关心其它人的编码细节就能协调开发，减少沟通成本。

API文档可以让作者自己书写，但毫无疑问书写文档的时间是非常长的，而且现代软件项目的需求经常改变，这就意味着每次修改需求都要重新修改源码和对应的文档，其维护的成本是相当大的。

因此现实很少有人会花额外时间来编辑API文档。

如果将文档直接以注释的方式写进代码里，这样源码和文档总是出现在一起，修改的时候可以一并修改，这样就能大大减少维护文档的时间成本了。

同时也方便其他人在阅读源码时通过注释来更直观地理解功能。

如图1-1就是一个典型的文档注释。

图11文档注释

文档生成工具可以提取源码中的注释，并最后生成一个可供人直接阅读的API文档。

使用一些工具来生成API文档自然可以节约额外的文档书写时间，也可以在源码被修改后重新生成文档，而不需要每次都手写文档。

因此，开发一个优秀的文档生成工具是非常有必要的。

传统的API文档都是一个类似word的本地数据文件，它确实完成了API文档所应该拥有的功能。

但在web2.0时代，如果能让更多人通过网页参与API文档内容的讨论，则可以帮助作者修正错误，更帮助其他读者理解。

同时还能让来自不同地区的读者在网站上共同学习、共同进步。

因此生成的文档可以让读者可以就某个API进行评论。

在线API文档也方便读者浏览文档，读者不需要安装额外的软件，只需一个浏览器即可直接打开文档。

1.2国内外研究发展现状

目前主流的编程语言都有相应的文档生成工具。

比如Java语言可以使用javadoc来生成文档，生成的文档非常精确。

目前国外最有名的JavaScript文档生成工具为jsdoctoolkit，它的工作原理是在强制作者在代码中书写一些标记，然后jsdoc文档会分析这些标记来构建文档，并确保最后生成的文档是正确的。

虽然使用这个方式比较容易理解和使用，但由于它只分析这些标记，而忽略源码本身，很多可以从源码中得到的信息必须在标记中重新写明，所以让文档书写的工作量倍增。

此外，它还具有以下缺点：

1.只有命令行模式，新用户不容易上手。

2.由于是国外的项目，中文容易出现乱码。

3.生成的文档比较简单，信息量少。

因此它不是完美的解决方案。

目前最有名的在线API文档系统为MSDN，MSDN库为使用Microsoft®工具、产品、技术和服务的开发人员提供必不可少的信息资源。

MSDN库包含操作方法和参考文档、示例代码、技术文章和其他内容。

但MSDN仅针对指定平台才能使用，而且MSDN是不开源的，无法被其他用户使用。

1.3研究开发的基本目标

该软件主要分三个部分：

（1）软件主体。

本程序目标用户为源码作者，这些用户可以通过这个软件进行文档生成操作，同时软件也会向它们报告解析错误。

（2）文档网站。

网站用于展示文档，同时网站允许使用不同的模板风格，方便用户自定义网站。

（3）可以为最终用户提供联机使用帮助，包括本系统的说明信息、使用方法和步骤以及版权信息和联系方式等。

1.4本文的组织结构

本文共分为六章，各章内容如下：

第一章，绪论,讨论课题的研究目的和意义、研究现状，研究主要内容。

第二章，相关方法和技术介绍。

第三章，重点介绍了文档生成过程的具体需求。

第四章，对整个系统进行设计和实现。

重点介绍分析算法的实现和最终文档页面的代码设计。

第五章，系统测试与系统使用说明。

第六章，对系统开发进行总结并提出下一步工作。

第二章方法与技术

本系统涉及了多个领域的知识。

用户可以通过一个本地软件界面来生成文档，而生成的文档本身又是一个Web页面，并且还需要开发一个后台动态网站才能实现在线评论。

软件的主要任务是生成文档，文档解析核心算法是本系统开发的主要难点，它需要用到编译原理相关的知识。

2.1软件运行环境

本系统基于.NetFramework3.5坏境开发。

.NetFramework坏境是支持生成和运行下一代应用程序和XMLWebService的内部Windows组件。

[1]

2.1.1客户端环境要求

安装有.NetFrameworks3.5的windows系统。

2.1.2服务器环境要求

（2）服务器:

IIS（InternetInformationServer）7。

IIS是InternetInformationServices的缩写，是一个WorldWideWebserver。

Gopherserver和FTPserver全部包容在里面。

IIS意味着你能发布网页，并且有ASP（ActiveServerPages）、JAVA、VBScript产生页面，有着一些扩展功能[2]。

（3）数据库：

Access2007

Access2007是MicrosoftOffice2007家族中专业的数据库管理系统，它具有强大的数据管理和分析功能。

作为一种新型的关系型数据库管理系统，它能帮助用户处理各种海量信息。

它不仅能存储数据，更重要的是能够对数据进行分析和处理，使用户方便快捷地聚聚各种有用的数据[3]。

2.2WinForm简介

WindowsForms（Windows窗体）是1个新的窗体包，它使得开发人员可以创建基于Windows的应用程序，来充分利用MicrosoftWindows操作系统中丰富的用户界面特性。

WindowsForms是新的Microsoft．NETFramework的一部分，它使用了许多新技术，包括1个公共应用程序框架、受控的执行环境、集成的安全性和面向对象的设计原则。

此外，WindowsForms完全支持快速、容易地连接XML网络服务和在ADO．NET数据模型基础上创建丰富的、数据感知（data．aware）的应用程序。

利用VisualStudio．NET中新的共享开发环境，开发人员可以使用任何支持．NET平台的语言。

开发人员可以使用任何支持．NET平台的语言。

在Visual C#中构建Windows窗体程序时需要向项目添加窗体，将控件拖放到窗体，然后在控件双击，即可编写窗体背后的代码。

开发人员使用这种熟知的模型，来迅速地构建桌面应用程序。

C#的Windows Forms有1个重要的新特性一可视化集继承，它将提高开发人员的生产力，促进代码的重用。

C群的Windows Forms还可以创建支持最广泛的用户群的应用程序。

使用c#的Windows Forms应用程序，不需要将应用程序部署到最终用户的桌面上。

用户可以通过在浏览器中输入1个URL地址即可调用这个应用程序。

应用程序将下载到客户端机器中，在1个安全的执行环境中运行，然后在完成后自我删除。

同时，c#的Windows Forms给开发人员提供了创建基于Windows的应用程序所需的多种技术。

不仅有用于调整用户界面的新控件和特性，还提供了灵活的部署和集成的安全特性[4]。

Windows窗体提供了一套丰富的控件，并且开发人员可以定义自己有特色的新的控件[5]。

2.3ASP.NET简介

ASP.NET是一个后台动态语言技术。

它是开发人员和构架师共同思考关于未来Web开发的发展方向而得出的结果[6]。

生成的文档本身不依赖于ASP.NET，它仅仅需要用ASP.NET为它提供后台提供评论服务接口。

2.4AJAX简介

Ajax是AsynchronousJavaScriptandXML的缩写。

Ajax并不是一门新的语言或技术，它实际卜是几项技术按一定方式的组合，在共同的协作中发挥各自的作用，它包括：

使用XHTML和CSS标准化呈现：

使用DOM实现动态显示和交互；使用XML和XSLT进行数据交换与处理；使用XMLHttpRequest进行异步数据读取；最后用JavaScript绑定和处理所有数据。

其中XMLHttpRequest，JavaScript和DOM是Ajax技术的核心[7]。

Ajax使得Web应用程序的客户端可以不断从Web服务器更新部分页面，用户不必再提交表单，或者离开当前的页面。

客户端的脚本代码（通常是JavaScript）可以向页面的部分片段（Fragment）发起异步的，或者非阻塞（Non-Blocking）的请求。

这些片段可以是一些原始的数据，在客户端再被转成HTML代码，也可以本身就是HTML代码，直接插入到浏览器的文档（Document）对象中。

不管怎样，在服务器端完成对请求的处理，并将响应片段返回给客户端浏览器之后，客户端的较代码都会使用这些数据来修改页面中的文档对象模型（DocumentObjectModel,DOM）。

这种方法不仅能够满足我们对快速、平滑更新的要求，更重要的是能够以异步的形式发送请求，因此，即使在请求的处理过程中，用户也可以继续使用应用程序[8]。

生成的文档的所有数据都是通过AJAX动态载入然后转成HTML代码后显示的。

这样可以加速文档初始化，还可以保证最佳的用户体验。

2.5编译原理

编译原理起初用于将源代码编译成可执行文件。

本系统的重点是将源代码翻译成文档，因此只需要编译原理中词法分析、语法分析的技术。

使用语法分析的方式来分析源码是本软件和jsdoc的最大的区别。

Jsdoc只以文本方式去分析注释，它忽略了代码本身所展示的信息。

而如果先解析语法，然后进行文档分析，就可以充分获取语法树种提供的信息来补全文档。

这样可以大大提高分析的正确性。

2.6系统构架:

B/S构架

B/S（Browser/Server）结构即浏览器和服务器结构，随着互联网的快速发展，越来越多的应用选择了B/S构架。

相对于C/S结构属于“胖”客户端，需要在使用者电脑上安装相应的操作软件来说，B/S结构是属于一种“瘦”客户端，大多数或主要的业务逻辑都存在于服务器端[9]。

2.7主要开发语言

本系统采用C#开发。

C#是一门间的、现代化、面向对象和类型安全的编程语言。

C#提供一些特性来帮助构建健壮、耐用的应用程序:

垃圾收集会自动回收不再使用的对象所占用的内存;异常处理提供了一种结构化且可扩展的方式来检测错误和恢复;而语言的类型安全设计则可以防止读取未初始化的变量、数组越界或进行未检测的类型转换[10]。

2.8开发工具

2.8.1VisualStudio2010

VisualStudio是微软公司出品的一款大型应用软件，从最初的VisualStudio97开始就成为了编程的重要工具。

VisualStudio是一天完整的开发工具集，保护了大量的公墓内，它主要用于生成ASP.NETWeb应用程序、XMLWebServices、桌面应用程序和移动应用程序[11]。

VisualStudio2010是VisualStudio的最新正式版。

2.8.2Firebug

Firebug是目前最流行的网页开发调试工具。

它提供了包含JavaScript控制台、HTML节点查看、CSS即时调试、JavaScript调试等功能，让开发网页更方便。

因为整个文档是一个比较大型的一页式应用，因此非常需要这样一个代码调试工具来确保系统可以稳定运行。

Firebug的运行界面如图2-1。

图21Firebug运行界面

第三章需求分析

3.1软件主体

软件主体是面向最终用户的产品，最后用户使用此软件来达到文档生成的目的。

此处的功能设计是为用户角色的而设计的[12]。

3.1.1用例图

图31软件主体用例图

3.1.2新建和保存项目

新建一个文档项目之后，用户可以在此项目中添加用于生成文档的源文件和文件夹。

用户也可以保存这个项目，而不需要每次生成的时候都重新添加文件。

3.1.3编辑项目

（1）添加文件

用户可以单独添加用于生成文档的源文件。

而且，为了更好的用户体验，用户也可以直接将资源管理器中的文件拖拖动到软件界面实现添加操作。

（2）添加文件夹

一般地，一个项目包含很多源文件，如果每个单独添加，操作会非常麻烦，因此这里也允许用户直接添加整个文件夹。

软件会自动搜索这个文件夹所有*.js文件。

同样地，用户也可以直接拖动一个文件夹到软件界面实现添加操作。

（3）删除文件

用户可以主动删除已添加的项。

为了更好的用户体验，当用户选择一项之后按DELETE，也可以快速删除项。

当用户同时删除多项时，应该给予用户确认后再进行删除。

（4）移动文件顺序

文件的顺序直接关系到后面文档解析的结果，因此必须提供一个改变文件添加顺序的功能，让用户根据需要更改源文件的解析顺序。

（5）项目属性

文档生成的时候有很多选项，用户可以在项目属性面板里修改这些选项。

3.1.4编译项目

编译项目即生成文档。

当项目编辑完成后，就可以开始真正的文档生成操作了。

软件会向用户显示一个控制台窗口，随时向用户报告生成进度。

如果生成时发现错误和警告，也会通过控制台窗口向用户报告。

因为文档生成是一个比较费时的过程，用户也可以根据需要随时中止文档生成操作。

3.2生成的文档界面

多媒体数据的格式有很多，常见的有Word、PDF和CHM。

但是大部分格式都需要在本地安装格外软件，且不适合API文档的信息展示方式。

而如果使用HTML作为文档数据载体，将可以带来这些好处:

（1）如今现有的每个Web浏览器都能理解这种语言[13]，而且大部分电脑都安装有浏览器，因此目标平台广泛。

（2）可以将文档放到WEB服务器，让用户在线浏览。

（3）样式定制方便。

所以软件最后生成的是文档网页，并且网页的布局和交互类似于传统的CHM格式文件。

界面的左侧显示一个类图导航。

通过这个导航可以找到任何API。

点击导航上的项，可以在界面的右侧浏览此API有关的详细信息。

用户在查看API文档的时候往往需要打开多个页面进行比较浏览，所以整个页面模拟选项卡的布局，方便用户同时打开多个文档并进行对比浏览。

尽管Web应用有这样或那样的优点，但作为一种应用媒介，它也有一个大的缺点。

就是网页需要刷新才能获取新数据。

因此我们需要使用AJAX技术来填补这个空白[14]。

3.3用于在线可评论的文档

传统的文档都是静态数据，用户只能浏览而不能参与评论。

在Web2.0下，社区化的文档更能帮助读者理解文档内容。

当用户打开文档界面时，文档会从服务器自动载入相关的评论。

用户还可以在任何页面添加自己的评论。

3.4文档调试工具

最终的文档是根据代码中的注释提取出来的，源文件中的注释不可能一次性就写正确，往往需要反复修改才能确保最终生成的文档是正确的。

但每次生成操作生成的是一个最终的文档页面，这是一个比较漫长的过程。

因此还需要提供一个文档调试工具，这个工具只解析文档并向用户报告文档解析结果，而不生成最后的文档。

用户可以使用这个工具来排除文档注释中的错误，然后使用软件主体来生成最后的文档。

第四章系统设计实现

4.1文档解析核心

4.1.1数据流图

语法解析器

文档解析器

图41数据流图

4.1.2类图

图42类图

DocProject类负责管理整个文档生成操作。

文档生成操作分文档解析和生成最终文件两步。

文档解析由DocParser类完成。

生成最终文件由DocGenerator类完成。

因为文档解析的步骤较为复杂，因此文件解析又分成语法树解析、文档注释解析、文档注释分析、文档注释提取。

这些操作分别由JavascriptParser类、JavaCommentParser类、DicAstVisitor类、DocMerger类完成。

4.1.3相关的实体类

为了实现相关功能，还需要定义一些实体类。

（1）XXCommentNode类

XXCommentNode存储某个节点的数据。

比如ReturnCommentNode是一个包含ReturnType和ReturnSummary的一个结构。

（2）DocComment类

DocComment