javascript document tool
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
example
lib
main.js
package.json
readme.md

readme.md

JDT (Javascript Document Tool)

### 安装
$ 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注释行被解析为一个包含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"
}
### 常见问题
Q: 为什么我的注释块生成json后会有一个名为 "" 的值

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

注释代码:

/**
 * text
 */

生成结果:

{
    "" : "text"
}

配置别名:

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

执行结果:

{
    "value" : "text"
}
Q: 为什么我指定了父级@tag,但是并没有起作用。

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