node package manager

jdt

javascript document tool

JDT (Javascript Document Tool)

### 安装
$ npm install jdt
### 如何开始 jdt( `` sUri ``, `` [oArgs] ``);
var jdt = require("jdt");
jdt( '/data/data1/project/js');
### 参数
jdt("/data/data1/project/js")
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注释行被解析为一个包含tagvaluedata三部份的对象

默认规则:

  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"
}
### 常见问题

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

注释代码:

/**
 * text
 */

生成结果:

{
    "" : "text"
}

配置别名:

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

执行结果:

{
    "value" : "text"
}

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