開源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）
}
 *