Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    jdtpublic

    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

    Keywords

    none

    install

    npm i jdt

    Downloadsweekly downloads

    19

    version

    0.1.8

    license

    none

    repository

    github.com

    last publish

    collaborators

    • avatar
    • avatar