JDT (Javascript Document Tool)

• 安装
• 如何开始
• 参数
• 文件过滤
• 指定@tag的合并
• 指定@tag的父级
• 指定@tag的别名
• 自定义@tag的格式化方法
• 常见问题

### 安装

$ npm install jdt

### 如何开始 jdt( `` sUri ``, `` [oArgs] ``);

var jdt = require("jdt");
jdt( '/data/data1/project/js');

### 参数

sUri : String 必选参数，资源路径

jdt("/data/data1/project/js")

oArgs : Object 非必选参数，配置参数

jdt("/data/data1/project/js", {
	//目录遍历会调用此方法进行过滤
	//对参数uri进行检查如果保留则返回true
	  "filter"  : function(uri){
	  	...
	  	return true;
	  }
	//配置文件的扩展名，默认为".js"
	, "extname" : ".js"
	//配置@tag标签的规则
	, "config"  : {
		"tag"  : 
		{
			//当前@tag的父级@tag名称，可以是字符串或数组
			 "parent" : "tag",
			//当前@tag如果出现多次是否合并为数组
			//该值不为空时会将该注释块中所有相同父级的同名@tag合并为数组
			//反之则结果则以字符串型式显示，如果同一注释块中有多个仅保留第一个
			"meage"  : true,
			//当前tag格式化函数，返回结果会显示为return的内容
			//oData是一个Object包函有三个字段 {tag:tag, value:value, data:data }
			//注意：如果return的内容是字符串类型，则指定parent为当前@tag的将无法成为其子集
			"format" : function(oData){
				var data = {};
				...
				return data;
			}
		},
		"tag1" : 
		{
			...
		}
	}
}

### 文件过滤

以过滤 .svn _svn为例

var path = require("path")
  , basename = path.basename;

jdt("/data/data1/project/js", {
	filter : function(uri){
	    var base = basename(uri);
	    
	    if(!(/^\.|_/.test(base))){
	       return true;
	    }
	    return false;
	}
})

### 指定@tag的合并

通常在注释中会出现多个一样的@tag，如果对该@tag配置了merge=true那么该@tag将被合并成为一个数组。

如果没有配置merge参数，结果仅显示首个@tag中的内容

注释代码:

/**
 * @import a.b.c
 * @import d.e.f
 * @import g.h.i
 */

js代码:

jdt("/data/data1/project/js", {
	config:{
		"import":{
			"merge" : true
		}
	}
})

执行结果:

{
	"import": [
		"a.b.c",
		"d.e.f",
		"g.h.i"
	]
}

### 指定@tag父级

我们以家庭为例，成员包括父亲、母亲、及孩子，而我们需要在节构上表明成员与家的关系就会用到parent这个配置.

注释代码:

/**
 * @family a
 * @father d
 * @mother c
 * @child  d
 */

js代码:

jdt("/data/data1/project/js", {
	"config":{
		"father":{
			"parent" : "family"
		},
		"mother":{
			"parent" : "family"
		},
		"child" :{
			"parent" : "father"
		}
	}
})

执行结果:

{
	"family": {
		"value": "a",
		"data": "",
		"mother": "c",
		"father": {
			"value": "d",
			"data" : "",
			"child": "d"
		}
	}
}

### 指定@tag别名

当我们需要给提取的@tag一个新的标签名称时，你会用到 alias 这个配置.

假设我们让提取的@import显示为@imports

注释代码:

/**
 * @import a.b.c
 * @import d.e.f
 * @import g.h.i
 */

js代码:

jdt("/data/data1/project/js", {
	config:{
		"import":{
			"merge" : true,
			"alias" : "imports"
		}
	}
})

执行结果:

{
	"imports": [
		"a.b.c",
		"d.e.f",
		"g.h.i"
	]
}

### 自定义@tag的格式化方法

当@tag的解析需要特定处理，可以通过format配置@tag的解析方法

在默认规则中，@tag注释行被解析为一个包含tag、value、data三部份的对象

默认规则：

1. 如果@tag被指定为另一@tag的父级，那么该@tag的内容会自动变为一个Object对象 2、如果@tag没有被任何@tag指定为父级，并则没有配置 merge ,那么这个@tag的内容会是一个String字串

2. 格式化函数必需有返回值

3. 如果返回值是一个String类型，那么对该@tag 配置的 parent 将会失效

注释代码:

/**
 * @tag value
 * data;
 */

注册格式化方法后，会得到一个类似这样的对象

{
	"tag"   : "tag",
	"value" : "value",
	"data"  : "data"
}

以example为例，注册一个example的格式化方法

jdt("/data/data1/project/js", {
	config:{
		"example":{
			"format" : function(oData){
				var data = ["@" + oData.tag, '|', oData.value, '|', oData.data].join(" ");
				return data;
			}
		}
	}
})

得到结果:

{
	"example": "@example | abc |  abcdefg"
}

### 常见问题

Q: 为什么我的注释块生成json后会有一个名为 "" 的值

A: jdt以@tag为解析标识，如果注释块中的文字没有归属，则会产生一个空的值存储这段文字，如果想为这个值设置一个tag可以使用 alias 配置别名

注释代码:

/**
 * text
 */

生成结果:

{
    "" : "text"
}

配置别名:

jdt("/data/data1/project/js", {
    "config" : {
		"" : {
			"alias" : "value"
		}
	}
})

执行结果:

{
    "value" : "text"
}

Q: 为什么我指定了父级@tag，但是并没有起作用。

A: 通常这种情况与父级注册的格式化方法有关，请参考 format