用于Javascript的文档生成软件的开发总结

　　近期一直在做Js文档生成软件。

　　目前占据这个领域的主要就是 jsdoc 开源项目。先介绍下 jsdoc 本身，它是用Java开发的(其实主要是Javascript开发) 基于字符串直接处理的文档工具。 因为Javscript非常灵活，Javascript的文档生成自然也比不上Java之类的准确、有效。jsdoc本身要求在注释中大量使用一些标签来告诉文档生成器这是一个类、属性、方法或其它的类型，jsdoc在解析中是通过上下文来决定变量的归属，比如上文使用 @class 标识类， 下文的 @method 就自动处理为上个 @class 所指的类，而完全忽视了代码自身的逻辑。

　　且不说jsdoc的方法是否方便、有效。总之，我要做的是基于语法分析而生成文档的工具。　

　　我目标是生成完全面向对象阻止的文档，即最后的文档最高级是名字空间(包) ， 下级是类， 再下级是成员。

　　1. 成员的归类。一个变量在定义后，它到底属于哪个父成员，这是文档分析必须要分析出的。

/**
* 将当前值转为数字。
*/
Boolean.prototype.toNumber = function(){
return +this;
};

　　从这段代码可知: 有一个 toNumber 成员， 其父成员为 Boolean.prototype ， 这个情况可以轻松检测所在成员，但假如换一个写法，比如 Ext 中的写法是:

/**
* 将当前值转为数字。
*/
Ext.extend(Boolean.prototype,{  toNumber: function(){
return +this;
}}  );

　　这就很麻烦了，因为文档分析程序不肯能去执行这个代码，它当然不知道 toNumber 的父成员。 jsdoc采用最近使用的 @class 最为其父成员。但这样很容易导致 @class 多很多错误的成员。

　　最终我采用作用域的分析方式。即 函数调用 或 函数定义 被作为一个作用域。它们之前的 @class 将被理解为这个作用域内成员的父成员。即代码应该这样注释:

/**
* 将当前值转为数字。 * @class Boolean
*/
Ext.extend(Boolean.prototype,{  toNumber: function(){
return +this;
}}  );

@class Boolean 只对此函数有效，即 @class 只解释相邻的作用域。 同理有:

/**
* 将当前值转为数字。 * @class Boolean
*/
(function(){  function toNumber(){
return +this;
}})();

由于这是函数定义，所以函数内部的成员的父成员也是 @class Boolean 。

　　当然，这些都是无理的推算，肯能导致错误结果，可以通过指定 @memberOf 来覆盖自动判断的父变量。

　　以上对于 @class C ， 成员解释为 C.prototype.p

　　对于 @namespace C , 或成员已记 @static, 解释为 C.p

2. 具备识别继承、原型的功能。

比如 A.prototype = new B 是很典型的继承代码。

通过模拟运行可以实现 原型操作。

3. 根据平时写Javascript的经验，再参考jsdoc， 最终我决定将使用以下几个系统标签，它们将为文档生成做出伟大贡献。

全局标签

　　全局标签主要用于全项目或文件的描述。一般全局标签只能在文件顶部使用。

@projectDescription Summary 当前项目功能描述

@author Summary 代码的作者

@lisense Summary 代码的协议

@version Summary 代码的版本

@fileOverview Summary 当前文件描述

@file Summary 表示当前文件名，默认为真实文件名

公开标签

以下标签可以在任何位置使用，就像 HTML 中任何标签都有 tagName 的属性。

@summary Summary 注释的简介 - 一般不需要直接使用这个标签， 因为注释的最开始处到第一个可解析的标签前的文字就是 @summary 标签。即: /** 内容 */ 等价于 /** @summary 内容 */

@remark Summary 备注 - 一般不需要直接使用这个标签， 因为注释中已经使用了标签之后的文字就是 @remark 。即:
　　/**
* @return {Number}
　　 * 说明
*/
等价于
　　/**
　　 * @return {Number}
　　 * @remark 说明
　　 */

@ignore 忽略有这个标记注释。

@define {Type} {Type} 定义同意义的类型。 比如 @define {int} {Number} 这样就可以用 int 代替 Number

@define Name Name 定义同意义的注释， 使用 define 可以定义标签的 别名。比如 @define description summary 之后就可用 @description 替代 @summary

@since [Summary] 指示自指定的版本提供。

@deprecated [Summary] 指示一个成员已经废弃。

@see Link 指向一个文件的链接。

@example Summary 示例。

@syntax Summary 手动指定语法。

@name Name 名字。

@memberOf Name 指示父成员。

@type Type 指示类型。

类型说明

@class [Name] 指示这是一个类。

@enum [Name] 指示这是枚举。

@interface [Name] 指示这是一个接口。

@member [Name] 指示这是一个成员。

@property [{Type}] [Name] 指示这是一个属性。

@field [{Type}] [Name] 指示这是一个字段。

@method [Name] 指示这是一个方法。

@event [{Type}] [Name] 指示当前类的事件。

@getter [{Type}] [Name] 指示这是一个只读属性。

@setter [{Type}] [Name] 指示这是一个只写属性。

@constructor [Name] 指示这是构造函数。

@config {Type} [Name] 指示这是类的配置成员。

属性说明

@public 指示公开

@private 指示一个类或函数是私有的。

@protected 指示保护。

@internal 指示内部。

@final 指示一个函数是不能覆盖的。

@static 指示一个类是静态的。

@abstract 指示一个类是抽象的。

@virtual 指示一个类是抽象的。

@const 指示一个值是常量值。

其它

@extends Name 指示一个类派生了另一个类。

@implements Name 指示一个类派生了另一个类。

@param {Type} Name Summary 表示参数。如果是可选参数加上 [Name] ,如果是 随机参数 名字为 ... 如果有默认值， 使用 Name=Value 多类型使用任意符号分开。

@return [{Type}] [Summary] 返回 。

{@link Link} 链接。

{@code [{Type}] <<< Summary >>>} 代码。

@{ 表示字符 {

@@ 表示字符 @

@} 表示字符 }

@* 表示字符 *