把注释写到函数内部 -- 轻松生成 JavaScript API Doc

在线演示 http://runjs.cn/code/bjk0zqfl

<!-- lang: js -->
(function () {
    // 用闭包写 js 是最常规的方法
    var api = this.Api = {};
    // 这个简单正则下面要要用
    var ez = /^function.+\((.*)\)\s*{\s*\/\*+([\S\s]*)\*+\//;

    // 一些私有方法, 不暴露到 api 给用户使用
    function privately(){
        // something
    }

    // 下面的 api.show 是用户可见的, 我们把注释写到 函数里面

    api.show = function(msg){
        /* alert msg */
        alert(msg)
    }

    // 下面是最简单的 API Doc 生成方法

    api.docez = docez

    function docez(obj){
        /**
            docez 生成 JavaScript API Doc 数据
            与直接从源码提取注释不同, 直接忽略了私有方法.
        */
        var comment,api = Object.create(null);
        obj = obj || this;
        for (var name in obj){
            if(typeof obj[name]!=='function'){
                continue
            }
            comment = ez.exec(obj[name].toString())
            // 无注释, 简单跳过
            if(!comment) continue
            api[name]={
                params: comment[1],
                desc: comment[2]
            }
        }
        return api
    }

    // 下面提取 api 文档并以 JSON 显示出来
    document.getElementById('ApiDoc').innerText = JSON.stringify(api.docez(),null,4)

})()