jdt

javascript document tool

npm install jdt
72 downloads in the last month

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

npm loves you