毕业设计-javascript在线api文档生成.doc

本科毕业设计说明书（论文） （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, 文档生成, WinForm32AbstractJavaScript is the most popular script language nowadays, which is designed as a simple object-based script language to provide the ability of interaction for web pages at first. But along with the appearance of new web standards and the popularity of some JavaScript clients like Nodejs, the usage of JavaScript increases soon and the JavaScript projects become more complex, which leads to new requirement of JavaScript documentation as well.To avoid authors writing API Document word by word, there should be a powerful tool to export an API document from the source code automatically. The traditional related projects such as Jsdoc show their shortcoming when meeting new requirements. This article focuses on analyzing source code of JavaScript and then generating a full API document. The analyzing program is fit for JavaScript, which can save a lot of time for JavaScript authors.This article also talks about developing a program of WinForm to make it easier to operate. On the other hand, users can custom the templates of document if needed. The generated API document can run on ASP.NET server directly. Readers can view the document online and leave their comments on any page.Keywords：JavaScript, API, Document Generator, WinForm目录摘要IABSTRACTI第一章绪论31.1研究开发的目的31.2国内外研究发展现状41.3研究开发的基本目标41.4本文的组织结构5第二章 方法与技术62.1软件运行环境62.1.1客户端环境要求62.1.2服务器环境要求62.2WinForm 简介62.3ASP.NET 简介72.4AJAX 简介72.5编译原理82.6系统构架: B/S构架82.7主要开发语言92.8开发工具92.8.1Visual Studio 201092.8.2Firebug9第三章 需求分析103.1软件主体103.1.1用例图103.1.2新建和保存项目103.1.3编辑项目103.1.4编译项目113.2生成的文档界面113.3用于在线可评论的文档123.4文档调试工具12第四章 系统设计实现134.1文档解析核心134.1.1数据流图134.1.2类图144.1.3相关的实体类144.1.4DocProject 类的实现154.1.5DocParser类的实现164.1.6JavaCommentParser 类的实现174.1.7JavaScript 语法树构建器的实现174.1.8DocAstVistor 类的实现184.1.9DocMerger 类的实现184.1.10DocGenerator 类的实现194.2软件主体194.2.1界面布局194.2.2项目操作204.2.3软件实现204.3文档页面234.4在线文档评论244.5文档调试工具25第五章 系统测试275.1单元测试275.2系统功能测试27第六章 总结286.1完成的工作286.2下一步工作28参考文献29致谢31附录32附录1 毕业设计文献综述32附件2 毕业设计开题报告32附件3 毕业设计外文翻译（中文译文与外文原文）32图目录图 11文档注释3图 21 Firebug 运行界面9图 31软件主体用例图10图 41数据流图13图 42类图14图 43 DocData的字段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文档生成工具为jsdoc toolkit，它的工作原理是在强制作者在代码中书写一些标记，然后jsdoc文档会分析这些标记来构建文档，并确保最后生成的文档是正确的。虽然使用这个方式比较容易理解和使用，但由于它只分析这些标记，而忽略源码本身，很多可以从源码中得到的信息必须在标记中重新写明，所以让文档书写的工作量倍增。此外，它还具有以下缺点：1. 只有命令行模式，新用户不容易上手。2. 由于是国外的项目，中文容易出现乱码。3. 生成的文档比较简单，信息量少。因此它不是完美的解决方案。目前最有名的在线API文档系统为MSDN，MSDN 库为使用 Microsoft® 工具、产品、技术和服务的开发人员提供必不可少的信息资源。MSDN 库包含操作方法和参考文档、示例代码、技术文章和其他内容。但 MSDN 仅针对指定平台才能使用，而且MSDN是不开源的，无法被其他用户使用。1.3 研究开发的基本目标该软件主要分三个部分：(1) 软件主体。本程序目标用户为源码作者，这些用户可以通过这个软件进行文档生成操作，同时软件也会向它们报告解析错误。(2) 文档网站。网站用于展示文档，同时网站允许使用不同的模板风格，方便用户自定义网站。(3) 可以为最终用户提供联机使用帮助，包括本系统的说明信息、使用方法和步骤以及版权信息和联系方式等。1.4 本文的组织结构本文共分为六章，各章内容如下：第一章，绪论,讨论课题的研究目的和意义、研究现状，研究主要内容。第二章，相关方法和技术介绍。第三章，重点介绍了文档生成过程的具体需求。第四章，对整个系统进行设计和实现。重点介绍分析算法的实现和最终文档页面的代码设计。第五章，系统测试与系统使用说明。第六章，对系统开发进行总结并提出下一步工作。第二章 方法与技术本系统涉及了多个领域的知识。用户可以通过一个本地软件界面来生成文档，而生成的文档本身又是一个Web页面，并且还需要开发一个后台动态网站才能实现在线评论。软件的主要任务是生成文档，文档解析核心算法是本系统开发的主要难点，它需要用到编译原理相关的知识。2.1 软件运行环境本系统基于.Net Framework 3.5 坏境开发。.Net Framework 坏境是支持生成和运行下一代应用程序和XML Web Service 的内部 Windows 组件。12.1.1 客户端环境要求安装有.Net Frameworks 3.5 的 windows系统。2.1.2 服务器环境要求(1) 服务器: IIS(Internet Information Server) 7。IIS是Internet Information Services的缩写，是一个World Wide Web server。Gopher server和FTP server全部包容在里面。 IIS意味着你能发布网页，并且有ASP（Active Server Pages）、JAVA、VBScript产生页面，有着一些扩展功能2。(2) 数据库：Access2007Access 2007是 Microsoft Office 2007 家族中专业的数据库管理系统，它具有强大的数据管理和分析功能。作为一种新型的关系型数据库管理系统，它能帮助用户处理各种海量信息。它不仅能存储数据，更重要的是能够对数据进行分析和处理，使用户方便快捷地聚聚各种有用的数据3。2.2 WinForm 简介Windows Forms(Windows窗体)是1个新的窗体包，它使得开发人员可以创建基于Windows的应用程序，来充分利用Microsoft Windows操作系统中丰富的用户界面特性。Windows Forms是新的MicrosoftNET Framework的一部分，它使用了许多新技术，包括1个公共应用程序框架、受控的执行环境、集成的安全性和面向对象的设计原则。此外，Windows Forms完全支持快速、容易地连接XML网络服务和在ADONET数据模型基础上创建丰富的、数据感知(dataaware)的应用程序。利用Visual StudioNET中新的共享开发环境，开发人员可以使用任何支持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.3 ASP.NET 简介ASP.NET 是一个后台动态语言技术。它是开发人员和构架师共同思考关于未来Web开发的发展方向而得出的结果6。生成的文档本身不依赖于 ASP.NET，它仅仅需要用ASP.NET 为它提供后台提供评论服务接口。2.4 AJAX 简介Ajax是Asynchronous JavaScript and XML的缩写。Ajax并不是一门新的语言或技术，它实际卜是几项技术按一定方式的组合，在共同的协作中发挥各自的作用，它包括：使用XHTML和CSS标准化呈现：使用DOM实现动态显示和交互；使用XML和XSLT进行数据交换与处理；使用XMLHttpRequest进行异步数据读取；最后用JavaScript绑定和处理所有数据。其中XMLHttpRequest，JavaScript和DOM是Ajax技术的核心7。Ajax 使得Web应用程序的客户端可以不断从Web服务器更新部分页面，用户不必再提交表单，或者离开当前的页面。客户端的脚本代码(通常是JavaScript)可以向页面的部分片段(Fragment)发起异步的，或者非阻塞(Non-Blocking)的请求。这些片段可以是一些原始的数据，在客户端再被转成 HTML 代码，也可以本身就是HTML代码，直接插入到浏览器的文档(Document)对象中。不管怎样，在服务器端完成对请求的处理，并将响应片段返回给客户端浏览器之后，客户端的较代码都会使用这些数据来修改页面中的文档对象模型(Document Object Model, 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.1 Visual Studio 2010Visual Studio是微软公司出品的一款大型应用软件，从最初的 Visual Studio 97 开始就成为了编程的重要工具。Visual Studio 是一天完整的开发工具集，保护了大量的公墓内，它主要用于生成 ASP.NET Web 应用程序、XML Web Services、桌面应用程序和移动应用程序11。Visual Studio 2010 是 Visual Studio 的最新正式版。2.8.2 FirebugFirebug 是目前最流行的网页开发调试工具。它提供了包含JavaScript控制台、HTML节点查看、CSS即时调试、JavaScript调试等功能，让开发网页更方便。因为整个文档是一个比较大型的一页式应用，因此非常需要这样一个代码调试工具来确保系统可以稳定运行。Firebug的运行界面如图2-1。图 21 Firebug 运行界面第三章 需求分析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 用于在线可评论的文档传统的文档都是静态数据，用户只能浏览而不能参与评论。在 Web 2.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 表示文档中的一个注释信息，它是一个哈希表，存储了标签和值的一一对应关系。比如如下注释:/* * 说明 * since 1.3 * return Object value */对应解析的结果是一个 DocComment 对象,其内容为: summary => 说明 since => 1.3 return => ReturnCommentNode( Object value )其中， since 标签对应的数据是一个字符串，值为 1.3 。return 标签对应的数据是一个 ReturnCommentNode实例。(3) DocData DocData存储最后的文档解析数据。其数据结构如图4-3:图 43 DocData的字段其中，DocComments 为源文件中所有注释集合，它是按照注释在源文件的排列顺序出现的。Files 为源文件的列表，它和用户选择的解析源文件基本一致，但会自动重命名同名的文件，比如如果出现3个名为base.js的源文件，那么，第二个就会被重命名为base_1.js,第三个就会被重命名为base_2.js。Properties 是根据注释信息得到的项目属性。它是根据源文件中的一些特定标签得到的，比如源文件中的 copyright 标签的信息不会被保存到一个DocComment 对象中，而是被保存到 Properties 属性的。只有有限的几个内置标签才会被保存到 Properties 属性的。4.1.4 DocProject 类的实现DocProject 存储了项目的所有配置，软件的操作注意是对 DocProject 进行的。DocProject 提供的接口和需求一一对应。DocProject本身又是一个哈希表15，它存储了一次文档生成的全部配置。DocProject 最主要的核心解析函数如下:public override void Build() / 首先获取原始的文档数据。DocData data = Parse(); / 然后使用 DocGenerator 进行最终文件生成。 new DocGenerator(this).Generate(data);public DocData Parse() / 创建一个 DocParser 来解析文档。 DocParser parser = new DocParser(this);/ 使用 DocParser 来为添加的每个文件和文件夹单独解析。for(int i = 0; i < Items.Count; i+) parser.ParseItem(Itemsi); / 返回解析之后得到的原始文档数据。 return parser.Data;文档解析后得到一个 DocData 对象，它是 DocGenerator 的输入。为了支持多语言的文档生成，这里还定义了一个DocProjectBase 类，然后可以使用工厂模式创建不同语言的 DocProject 对象 。工厂模式是用于将生成对象的步骤进行封装的创建型模式16。4.1.5 DocParser类的实现DocParser 会先解析语法树，同时提取注释节点。语法树是分析树的浓缩表示，对表示语言结构是有用的。语法树作为中间表示，允许把翻译从分离处理。在分析期间完成翻译固然有很多邮电，但也存在一些问题，如在分析期间调用的翻译例程受到两个限制。首先，适于分析的文法可能并不反映语言成分的自然层次结构。其次，分析方法对分析树结点的考察次序有一定的限制，它所限制的次序肯能和一个结构中各成分信息的使用次序并不一致17。DocParser 主要提供的是解析文件的接口。解析文件先将文件解析成语法树。以下是解析文件的伪代码:public void ParseFile(string path, string file) _currentSource = file;_comments.Clear();/ 解析语法树。Script script = _parser.ParseFile(path, _project.Encoding);ParseScript(script);然后对语法树进行分析遍历。void ParseScript(Script script) / 获取语法分析返回的注释列表。DocComment map = _comments.ToArray();/ 进行文档解析。_docAstVistor.Parse(script, map);/ 文档合成。 _docMerger.Parse(map);DocParser 还负责提取源码中的注释。但真正的解析操作是调用 JavaCommentParser 类完成的。 4.1.6 JavaCommentParser 类的实现JavaCommentParser 负责解析一个文档注释，然后得到一个注释的信息，并将这些信息存入一个 DocComment 实例。JavaCommentParser 在设计上使用单例模式以节约内存。JavaCommentParser 的主要功能其实就是注释片段的词法解析。这样无论注释怎么写，其它程序都可以统一处理，而不需要关心原注释的格式问题。4.1.7 JavaScript 语法树构建器的实现文档解析要求语法树构建器提供这两个特别的功能:(1) 允许文档解析器处理文档中的注释，而不是忽略这些注释。(2) 允许忽略语法错误。所以网上没有现成的满足这两个特别需求的解析器，因此这里重复开发了一个JavaScript语法构建器。构建器是完全按照 ECMA 262 中规定的文法完成的。语法解析器提供了一个 IDocParser 接口，如果外界需要处理在语法解析同时解析注释，可以定义一个类来实现这个接口，并绑定这个类到语法解析器。这里由DocParser 负责实现这个接口，它会拦截 /* 开头的注释进行文档解析。4.1.8 DocAstVistor 类的实现DocAstVistor 主要的目标是遍历语法树，根据语法树的信息自动填充文档注释。因此，DocAstVistor 可以让文档作者少写很多注释内容。DocAstVistor 所做的主要工作有:(1) 自动识别变量名:比如有代码:/*说明*/var a = 2;DocAstVistor 可以根据代码中的变量a，将注释补成 /*说明 name a*/ ，这样在最后的文档中就可以告诉用户这是一个名字为a的变量。调用时也使用这个名字。(2) 自动识别所属成员:比如有代码:/*class A*/*说明*/var a = 2;此时的a 会根据就近原则自动归类成 class A 的一个字段。(3) 自动识别默认值比如有代码:/*说明*/var a = 2;其默认值是 2，这个信息即可在最终的文档显示。(4) 自动识别参数信息函数定义里面已经写明了参数名，这时用户不需要在文档里重复写明这些信息。DocAstVistor 可以自动填充参数的信息。4.1.9 DocMerger 类的实现经过 DocAstVistor 解析出来的文档是一个列表。DocMerger 可以将这个列表形状改写成对应的变量树结构。比如:Class1.a 方法Class2.b 方法Class1.e 属性经过 DocMerger 改写后可以得到:Class1 类:成员有: a方法， e属性Class2 类:成员有: b 方法。DocMerger 处理过的文档已经接近人能直接阅读的组织结构了。4.1.10 DocGenerator 类的实现DocParser 负责解析文档的原始数据，而 DocGenerator 则根据原始数据来生成最后的文档页面。DocGenerator 主要做三件事情:(1) 遍历文档注释列表，为每一个注释生成一个详细信息。(2) 遍历变量树，用于文档的导航。(3) 遍历源文件，并拷贝到文档中，方便在文档中查看API的源文件。4.2 软件主体4.2.1 界面布局需求中指出，软件在使用时不仅只有一个窗口，还需要多个子窗口。所以，主窗体的布局使用分栏模式。最后的界面设计如图 4-4。图 44软件主体的布局软件使用.Net 提供的 SplitContainer 控件将窗口分成3块，每块都是允许折叠的区域。在运行时移动鼠标到拆分器控件上面， 会出现左右箭头光标，此时可以调节拆分器两边的宽度18。但 SplitContainer 只支持上下或左右的分割，所以，这里使用2个SplitContainer 进行嵌套，首先是上下分割的容器，然后对上容器进行左右分割。如此，就能实现图中的布局效果。4.2.2 项目操作所有的操作都是以项目为单位的，用户可以新建、打开或保存项目。一次文档生成也被理解是为对项目的编译。项目在保存时使用XML格式， XML(eXtensible Markup Language) 是SGML的一个子集其目标是能够以目前HTML可能实现的方式在Web上使用、接受和处理通用SGML。XML的设计目标是实现简便并且能与SGML和HTML共同操作19。在.NET中，XML作为数据格式和ADO.NET一起使用，发挥了重要的作用20。.net内置了XML解析器，让项目保存和载入功能很方便完成。因为所有的项目配置都存储在 DocProject 中，因此保存和载入项目其实就是序列号和反序列化这个对象的过程。DocProject 本身是一个哈希表，因此保存和读取项目时只要遍历其所有的键值对即可。4.2.3 软件实现最后的生成软件是一个小巧的WinForm本地软件。软件界面如图4-5。用户可以点击文件/新建项目，然后点击添加文件来添加要生成的源文件，也可以通过拖动来添加需要的文件和文件夹。列表框允许用户选择一项或多项，然后对这些项进行删除或移动操作，为了方便用户确认源文件，双击任一项可以帮助用户定位该项在资源管理器的位置。用户编辑的界面效果如图4-6。点击属性可以打开属性面板，如图4-7。属性面板是一个 .net 的 PropertyGrid 控件，该控件允许向用户显示一个表格，并通过这个表格修改一个代码中的任何对象。这里属性面板就是一个编辑 DocProject 对象的 PropertyGrid 控件。最后点击生成，等待软件生成完成。生成时，软件会自动向用户展示控制台窗口。生成时的界面如图4-8。图 45软件主体运行界面图 46编辑项目图 47设置项目属性图 48控制台4.3 文档页面生成的文档是一个一页式的富互联网应用。文档页面使用左右布局。左侧显示导航条。右侧显示温度内容。导航条是一个树结构的界面，一开始导航显示了全部的全局类，点击任一个类名字后可以展开显示这个类对应的成员。为了保证文档的载入速度，导航条的所有项都是按需加载的，而不是一次性全部载入完。比如当用户需要显示 Array.prototype.each 方法对应的A