欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

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

程序员文章站 2022-07-15 12:37:31
...

一、安装

所有安装方式基于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注释样例

开源OA平台教程:Jsdoc的安装及使用
            
    
    博客分类: O2OA二次开发手册企业信息化系统架构企业信息化系统 OA开源开源软件OA办公OA系统 

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注释样例

开源OA平台教程:Jsdoc的安装及使用
            
    
    博客分类: O2OA二次开发手册企业信息化系统架构企业信息化系统 OA开源开源软件OA办公OA系统 

/**
     * 你可以通过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;}
    };

 

六:类型定义注释样例

开源OA平台教程:Jsdoc的安装及使用
            
    
    博客分类: O2OA二次开发手册企业信息化系统架构企业信息化系统 OA开源开源软件OA办公OA系统 

/**
 * 附件数据结构.
 * @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)
}
 */

上一篇: 防卫

下一篇: DDD 领域驱动设计