开源OA平台教程：Jsdoc的安装及使用
程序员文章站
2022-05-29 22:50:58
...
一、安装
所有安装方式基于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） } */