JavaScript在线API文档生成文献综述

本科毕业设计文献综述

（2012届）

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

JavaScript在线API文档生成

引言

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

而API文档的手动书写是一个漫长费时的过程，使用一些工具来生成API文档自然是最佳的解决方案。

一、关于JavaScript的研究

1.1JavaScript 语言背景

JavaScript简称Js，是目前Web应用程序开发者使用最为广泛的客户端脚本编程语言，它不仅可用来开发交互式的Web页面，更重要的是它将HTML、XML和Java applet、flash等功能强大的Web对象有机结合起来，使开发人员能快捷生成Internet或Intranet上使用的分布式应用程序。另外由于Windows 对其最为完善的支持并提供二次开发的接口来访问操作系统各组件并实施相应的管理功能，JavaScript成为继.bat(批处理文件)以来Windows系统里使用最为广泛的脚本语言[1]。

1.2脚本语言

脚本语言是为了缩短传统的编写-编译-链接-运行（edit-compile-link-run）过程而创建的计算机编程语言[2]。此命名起源于一个脚本“screenplay”，每次运行都会使对话框逐字重复。早期的脚本语言经常被称为批量处理语言或工作控制语言。一个脚本通常是解释运行而非编译。脚本语言通常都有简单、易学、易用的特性，目的就是希望能让程序员快速完成程序的编写工作。

1.3JavaScript语言特性

JavaScript作为一门脚本语言，具有较大的灵活性[3]。作者可以在代码任意位置定义和使用一个函数，也可以在任意变量读写属性。

二、关于API文档生成的研究

2.1API 文档

API（Application Programming Interface,应用程序编程接口）是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件的以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节[4]。

API 文档则是专门用于描述API的文档。比如比较有名API文档如java 2 api 文档[5]。

2.2现有的API文档生成技术

目前主流的编程语言都有相应的文档生成工具，且这些工具也工作地很好，比如Java语言可以使用javadoc[6]来生成文档，生成的文档非常精确。

目前国外最有名的JS文档生成项目为Jsdoc Toolkit[7]，它的工作原理是在书写文档的时候额外提供一些标记，以让文档生成工具更好地理解，确保最后生成的文档是正确的。这样做就让书写文档的工作量倍增。因此它不是完美的解决方案。

2.3编译原理在API文档生成的应用

编译是为了解析源码，并根据源码生成对应的可执行文件。

现在的目标是API文档生成，因此需要用到编译技术中的词法分析和语法分析[8]技术，在词法分析同时，还需要额外进行API文档注释分析。

1)词法分析

一个词法分析器从输入中读取字符，并将它们组成“词法单元对象”[9]。

2)语法分析

语法分析器从词法分析器获得一个由词法单元组成的串，并验证这个串可以由源语言的文法生成[9]。JavaScript 语言遵循ECMA-262[10]语法规范，因此进行JavaScript语法分析时，必须严格按照其文档中的文法约定执行。JavaScript 在语法上符合LR1规范，因此可以使用LR1生成器来定制适用于JavaScript的语法分析器。

图2-1 语法分析的位置

3)注释分析

如果是一个完整的编译器，则需要后续的单元链接[11]、代码优化过程语法分析可以得到代码语法树，通过遍历这棵树，可以分析出某个位置的注释的意义。

4)文档合成

分析注释的时候，将创建一个临时变量域，分析这个变量域可以提取整个文档数据，提取的文档数据被存储为XML文件，这个步骤称为文档合成。

2.4基于DOM的XML文档解析技术

XML(可扩展标记语言)是W3C为适应Internet的发展，实现快速的电子商务和电子数据交换而推出的新型web语言．它具有自描述性、数据结构高度规范、良好的扩展性、以及其数据与平台无关性等诸多优点[12]。

文档对象模型DOM(Document object Model)是W3C为在内存中建立XML 文档的树结构提供的一种标准规范，XML文档中的每个元素、属性、CDATA 部分等都可以用DOM树结构中的节点来表示。DOM是处理XML数据的传统方法。使用DOM时，数据以树状结构的形式被加载到内存中[13]。

三、关于在线API文档的研究

3.1在线API文档

传统的API文档都是一个类似word的本地数据文件，它确实完成了API文档所应该拥有的功能。但在web2.0[14]时代，如果能让更多人通过网页参与API文档内容的讨论，则可以帮助作者修正错误，更帮助读者对某个API进行评论。同时还能让来自不同地区的读者在网站上共同学习、共同进步。

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

目前比较有名的在线API文档如MSDN[15]。

3.2在线API文档的实现

在线API文档本质上是一个web2.0的网站，因此需要用到https://www.wendangku.net/doc/fd14897088.html, 、SQL 数据库和XML相关技术才能实现这样的功能。

(1)https://www.wendangku.net/doc/fd14897088.html,

https://www.wendangku.net/doc/fd14897088.html, 不仅仅是Active Server Page (ASP) 的下一个版本,而且是一种建立在通用语言上的程序构架，能被用于一台Web服务器来建立强大的Web应用程序。https://www.wendangku.net/doc/fd14897088.html,提供许多比现在的Web开发模式强大的优势[16]。

(2)SQL数据库

SQL(Structured Query Language)，结构化查询语言。SQL语言的主要功能就是同各种数据库建立联系，进行沟通。按照ANSI(美国国家标准协会)的规定，SQL被作为关系型数据库管理系统的标准语言。SQL语句可以用来执行各种各样的操作，例如更新数据库中的数据，从数据库中提取数据等。绝大多数流行的关系型数据库管理系统都采用了SQL语言标准。虽然很多数据库都对SQL语句进行了再开发和扩展，但是包括Select, Insert, Update, Delete, Create,以及Drop 在内的标准的SQL命令仍然可以被用来完成几乎所有的数据库操作[17]。

(3)XML

XML解决方案的使用让我们的系统实现更加清洁和优雅，而且当前XML相对其它技术更为轻量和可塑。超链接标识文本语言（Hyper Text Markup Language ，HTML）和XML的区别是：HTML 只能使用预定的几个标签，这

些标签在文档类型定义（Document Type De?nition，DTD）定义。用户可以使用样式表修改这些元素的样式。而XML的优势则在于（1）它将数据的存储和展示分开，不同的样式可以用于显示相同的数据。这对程序来说非常有必要，因为不同的用户需要展示不要的数据，比如指定医生和病人等看到的是不同的格式的网页。（2）这个分析器可以直观地提取数据，实现数据交换[18]。

网站的数据是生成的文档内容，并且网站还允许用户注册登录、发布评论、搜索文档内容和检索文档索引。

四、关于生成工具软件的研究

作为一个软件，文档生成工具必须具有相应的用户界面。类似的项目有NDoc[19]，但该项目目前已经停止开发，不过其整体的软件设计是可以借鉴的。此外大部分文档生成工具仅提供了控制台命名接口，不具备图形界面。

有一个图形操作界面可以让软件操作更简单明了。

WinForm 具有下列优点：

(1)简单强大：Windows窗体可用于设计窗体和可视控件，以创建丰富的基

于Windows的应用程序。

(2)新的数据提供程序管理：数据提供程序管理提供易于连接OLEDB和

ODBC数据源的数据控件，包括Microsoft SQL Server、Microsoft Access、Jet、DB2以及Oracle等。

(3)安全：Windows窗体充分利用公共语言运行库的安全特性。这就意味

着，一切都可以通过Windows窗体来实现，包括在浏览器中运行的不可

信控件和用户硬盘上安装的完全可信的应用程序。

(4)灵活的控件：Windows窗体提供了一套丰富的控件，并且开发人员可以

定义自己有特色的新的控件[20]。

总结

软件的最终目标是生成API文档，其中经历了这里步骤：

(1)提供一个图形界面方便用户操作。

(2)分析和生成文档。

(3)将分析的结构转为一个在线网站。

软件用到了多方面的知识，其主要难点是解析部分。通过这个软件可以真正实现文档的自动化，把开发人员从书写文档的任务中解脱出来。

参考文献

[1]尼古拉斯·泽卡斯(Nicholas C.Zakas) ，李松峰、曹力译. JavaScript高级程序

设计(第2版)[M]. 人民邮电出版社,2010

[2]Alfred V. Aho, Monica https://www.wendangku.net/doc/fd14897088.html,m, 赵建华、郑滔译. 编译原理[M]. 第2版. 机械

工业出版社,2009

[3]弗拉纳根. 李强译. JavaScript权威指南(第5版). 机械工业出版社.2007-8

[4]百度百科[OL].https://www.wendangku.net/doc/fd14897088.html,/view/16068.htm

[5]Java2 文档[OL].https://www.wendangku.net/doc/fd14897088.html,/javase/1.3/docs/api/index.html

[6]Javadoc

Tool[OL]https://www.wendangku.net/doc/fd14897088.html,/technetwork/java/javase/documentation/index-js p-135444.html

[7]jsdoc-toolkit[OL].https://www.wendangku.net/doc/fd14897088.html,/p/jsdoc-toolkit/

[8]李文生.编译原理与技术[M]. 清华大学出版社,2009

[9]Alfred.V.Aho, Monica https://www.wendangku.net/doc/fd14897088.html,m, Ravi Sethi, Jeffrey D.Ullman 赵建华、郑淘、戴

新宇译.编译原理.机械工业出版社.2007

[10]E CMA. Standard ECMA-262[PDF],

https://www.wendangku.net/doc/fd14897088.html,/publications/standards/Ecma-262.htm.2011-1 [11](美)Alfred V.Aho;Monica https://www.wendangku.net/doc/fd14897088.html,m;Ravi Sethi;Jeffrey D.Ullman. Compilers:

Principles, Techniques, and Tools (2nd Edition)[M], 机械工业出版社，2008 [12]D eitel H m，Deitel P J．康博译．XML编程技术大全[M]．北京：清华大学出

版社，2000

[13]常春燕,李定主. XML文档解析技术研究[J]. 太原师范学院学报,2006

[14]百度百科[OL]. https://www.wendangku.net/doc/fd14897088.html,/view/733.htm

[15]M SDN[OL].https://www.wendangku.net/doc/fd14897088.html,/library/

[16]B ill Evjen, Scott Hanselman, Devin Rader, 李增民译. https://www.wendangku.net/doc/fd14897088.html, 4高级编程:

涵盖C#和https://www.wendangku.net/doc/fd14897088.html,(第7版)[M], 清华大学出版社,2010-9

[17]R obert Vieria. Beginning Microsoft SQL Server 2008 Programming[M], 清华大

学出版社, 2010

[18]G eorge Stalidis, Andriana Prentza, Ioannis N. Vlachos,Stavroula Maglavera,

Dimitris Koutsouris. Medical support system for continuation of care based on XML web technology[J]. International Journal of Medical Informatics.2001

[19]N Doc[OL].https://www.wendangku.net/doc/fd14897088.html,/

[20]钱哨.C# WinForm实践开发教程,中国水利水电出版社,2011