开源OA平台教程：Jsdoc的安装及使用

一、安装

所有安装方式基于node环境使用npm安装，未安装node可参考：https://www.cnblogs.com/bluedream2009/archive/2012/03/17/2402843.html

 

jsdoc中文文档：

https://www.html.cn/doc/jsdoc/tags-mixes.html

jsdoc安装命令：

npm i jsdoc

 

模板：tidy-jsdoc-o2

链接：https://www.npmjs.com/package/tidy-jsdoc-o2

安装命令：

npm i tidy-jsdoc-o2

 

二、配置

在前台目录中创建json文件，以 o2oa/o2web/jsdoc.conf.json为例

配置文件内容：

{
    "opts": {    //命令行参数，在配置文件中配置了就不要敲命令了
        "encoding": "utf8",               //文件编码utf8
        "destination": "./o2web/jsdoc/",          //输出目标文件夹
        "recurse": true,                 //是否递归抽取sorce/include配置的文件夹
        "template" : "./node_modules/tidy-jsdoc-o2", //模板路径
        "prism-theme": "prism-custom" //模板中的代码块样式主题
        //"tutorials": "./o2web/tutorials" //如果有教程，对应教程目录
    },
    "tags": {
        "allowUnknownTags": true, //允许jsdoc中未命名的标签
        "dictionaries": [   //标签库
            "jsdoc",
            "closure"
        ]
    },
    "source": {
        "include": [ //需要抽取文档的源文件夹
          "./o2web/source/x_component_process_Xform",
          "./o2web/source/o2_core/o2/xScript"
        ],
        "includePattern": ".+\\.js(doc|x)?$", //抽取的源文件名称正则表达式
        "excludePattern": "(^|\\/|\\\\)_" //排除的源文件正则表达式
    },
    "plugins": [ //启用插件
        "plugins/markdown", //把markdown转成html
        "plugins/summarize" //为每个doclet生成摘要
    ],
    "templates": {  //模板参数
        "cleverLinks": false, //@link标签是否呈现为纯文本
        "monospaceLinks": false
    },
    "metadata": {
        "title": "O2OA前台API" //最终生成的文档中标题
    }
}

三：执行

执行命令：

jsdoc -c ./o2web/jsdoc.conf.json

 

四：class注释样例

MWF.require("MWF.widget.Common", null, false);
/** @classdesc $Module 组件类，此类为所有组件的父类。
 * @class
 * @hideconstructor
 * */
MWF.xApplication.process.Xform.$Module = MWF.APP$Module =  new Class(
    /** @lends MWF.xApplication.process.Xform.$Module# */
    {
    Implements: [Events],
    options: {
        /**
         * 组件加载前事件。<br/>
         * 平台执行queryLoad事件的时候，组件还没有开始加载，这个时候可以根据条件修改组件的配置信息以改变加载细节。
         * @event MWF.xApplication.process.Xform.$Module#queryLoad
         * @example
         * var field = this.form.get("fieldName");
         * field.addEvent("queryLoad", function(){
         *
         * };
         */
        /**
         * 组件加载事件.
         * @event MWF.xApplication.process.Xform.$Module#load
         */
        /**
         * 组件加载后事件.
         * @event MWF.xApplication.process.Xform.$Module#postLoad
         */
        "moduleEvents": ["load", "queryLoad", "postLoad"]
    },
    initialize: function(node, json, form, options){
        /**
         * @summary 组件的节点
         * @see https://mootools.net/core/docs/1.6.0/Element/Element
         * @member {Element}
         * @example
         *  //可以在脚本中获取该组件
         * var field = this.form.get("fieldName"); //获取组件对象
         * field.node.setStyle("font-size","12px"); //给节点设置样式
         */
        this.node = $(node);
        this.node.store("module", this);
        /**
         * @summary 组件的配置信息，比如id,类型等.
         * @member {JsonObject}
         * @example
         *  //可以在脚本中获取该组件
         * var json = this.form.get("fieldName").json; //获取组件对象
         * var id = json.id; //获取组件的id
         * var type = json.type; //获取组件的类型，如Textfield 为文本输入组件，Select为下拉组件
         */
        this.json = json;
        /**
         * @summary 组件的所在表单对象.
         * @member {MWF.xApplication.process.Xform.Form}
         * @example
         * var form = this.form.get("fieldName").form; //获取组件所在表单对象
         * form.saveFormData(); //保存表单数据
         */
        this.form = form;
    },
    _getSource: function(){
        var parent = this.node.getParent();
        while(parent && (
            parent.get("MWFtype")!="source" &&
            parent.get("MWFtype")!="subSource" &&
            parent.get("MWFtype")!="subSourceItem"
        )) parent = parent.getParent();
        return (parent) ? parent.retrieve("module") : null;
    },
    /**
     * @summary 隐藏组件.
     * @example
     * this.form.get("fieldName").hide(); //隐藏组件
     */
    hide: function(){
        var dsp = this.node.getStyle("display");
        if (dsp!=="none") this.node.store("mwf_display", dsp);
        this.node.setStyle("display", "none");
        if (this.iconNode) this.iconNode.setStyle("display", "none");
    },
    /**
     * @summary 显示组件.
     * @example
     * this.form.get("fieldName").show(); //显示组件
     */
    show: function(){
        var dsp = this.node.retrieve("mwf_display", dsp);
        this.node.setStyle("display", dsp);
        if (this.iconNode) this.iconNode.setStyle("display", "block");
    }
});

五：module注释样例

/**
     * 你可以通过workContext获取和流程相关的流程实例对象数据。
     * @module workContext
     * @example
     * //您可以在表单或流程的各个嵌入脚本中，通过this来获取当前流程实例数据，如下：
     * var context = this.workContext;
     */
    this.workContext = {
        /**
         * 当前流程实例正在流转中，并且当前用户有待办，则返回当前用户的待办对象，否则返回null。
         * @summary 获取当前流程与当前用户相关的待办对象：task对象。
         * @method getTask
         * @static
         * @return {(Task|Null)} 当前用户的待办任务对象：task。当前用户没有对此流程实例的待办时，或流程实例已经流转结束，返回null.
         * @example
         * var task = this.workContext.getTask();
         */
        "getTask": function(){return ev.task || null;},
        /**
         * 获取当前流程实例对象：work对象或workCompleted对象。
         * @method getWork
         * @static
         * @return {(Work|WorkCompleted)} 流程实例对象；如果流程已结束，返回已结束的流程实例对象.
         * @example
         * var work = this.workContext.getWork();
         */
        "getWork": function(){return ev.work || ev.workCompleted;}
    };

 

六：类型定义注释样例

/**
 * 附件数据结构.
 * @typedef {Object} AttachmentData
 * @property {String} id - 附件id.
 * @property {String} name - 附件标题.
 * @property {String} person - 上传人.
 * @property {Number} orderNumber - 排序号.
 * @property {String} activityName - 上传的节点.
 * @property {Object} control - 当前登录人员对附件拥有的权限.
 * @property {Boolean} control.allowRead - 是否允许阅读.
 * @property {Boolean} control.allowEdit - 是否允许编辑.
 * @property {Boolean} control.allowControl - 是否允许设置.
 * @property {Number} length - 附件大小.
 * @property {String} createTime - 创建时间.
 * @property {String} updateTime - 修改时间.
 * @property {String} extension - 附件扩展名.
 * @example
 * {
    "id": "56c4e86f-a4c8-4cc2-a150-1a0d2c5febcb",   //附件ID
    "name": "133203a2-92e6-4653-9954-161b72ddb7f9.png", //附件名称
    "extension": "png",                             //附件扩展名
    "length": 43864,                                //附件大小
    "person": "xx@huqi@P",                          //附件上传人
    "lastUpdateTime": "2018-09-27 15:50:34",        //最后的修改时间
    "lastUpdatePerson": "xx@huqi@P",                //最后的修改人
    "activity": "e31ad938-c495-45a6-8d77-b8a9b61a165b", //附件上传的活动ID
    "activityName": "申请人",                           //附件上传的活动名称
    "activityType": "manual",                           //附件上传的活动类型
    "site": "$mediaOpinion",                        //附件存储位置（一般用于区分附件在哪个表单元素中显示）
    "type": "image/png"                             //附件类型（contentType）
}
 */