jsdoc文档
2016-08-19 16:23
99 查看
官网文档:http://usejsdoc.org/index.html
一个比较全的jsdoc示例
View Code
命令名描述
@param @argument 指定参数名和说明来描述一个函数参数
@returns 描述函数的返回值
@author 指示代码的作者
@deprecated 指示一个函数已经废弃,而且在将来的代码版本中将彻底删除。要避免使用这段代码
@see 创建一个HTML链接,指向指定类的描述
@version 指定发布版本
@requires 创建一个HTML链接,指向这个类所需的指定类
@throws @exception 描述函数可能抛出的异常的类型
{@link} 创建一个HTML链接,指向指定的类。这与@see很类似,但{@link}能嵌在注释文本中
@fileoverview(@file || @overview) 这是一个特殊的标记。如果在文件的第一个文档块中使用这个标记,则指定该文档块的余下部分将用来提供这个文件的概述
@class 提供类的有关信息,用在构造函数的文档中
@constructor 明确一个函数是某个类的构造函数
@type 指定函数的返回类型
@extends 指示一个类派生了另一个类。JSDoc通常自己就可以检测出这种信息,不过,在某些情况下则必须使用这个标记
@private 指示一个类或函数是私有的。私有类和函数不会出现在HTML文档中,除非运行JSDoc时提供了--private命令行选项
@final 指示一个值是常量值。要记住JavaScript无法真正保证一个值是常量
@ignore JSDoc忽略有这个标记的函数
@method == @func == @function 将这个函数定义为global下的methods类下
@function functionName == @func + @name functionName
@member 该
官方文档
@augments - Indicate this class uses another class as its "base."
@author - Indicate the author of the code being documented.
@argument - Deprecated synonym for @param.
@borrows that as this - Document that class's member as if it were a member of this class.
@class - Provide a description of the class (versus the constructor).
@constant - Indicate that a variable's value is a constant.
@constructor - Identify a function is a constructor.
@constructs - Identicate that a lent function will be used as a constructor.
@default - Describe the default value of a variable.
@deprecated - Indicate use of a variable is no longer supported.
@description - Provide a description (synonym for an untagged first-line).
@event - Describe an event handled by a class.
@example - Provide a small code example, illustrating usage.
@extends - Synonym for @augments.
@field - Indicate that the variable refers to a non-function.
@fileOverview - Provides information about the entire file.
@function - Indicate that the variable refers to a function.
@ignore - Indicate JsDoc Toolkit should ignore the variable.
@inner - Indicate that the variable refers to an inner function (and so is also @private).
@lends - Document that all an object literal's members are members of a given class.
{@link ...} - Like @see but can be used within the text of other tags.
@memberOf - Document that this variable refers to a member of a given class.
@name - Force JsDoc Toolkit to ignore the surrounding code and use the given variable name instead.
@namespace - Document an object literal is being used as a "namespace."
@param - Describe a function's parameter.
@private - Indicate a variable is private (use the -p command line option to include these).
@property - Document a property of a class from within the constructor's doclet.
@public - Indicate an inner variable is public.
@requires - Describe a required resource.
@returns - Describe the return value of a function.
@see - Describe a related resource.
@since - Indicate that a feature has only been available on and after a certain version number.
@static - Indicate that accessing the variable does not require instantiation of its parent.
@throws - Describe the exception that a function might throw.
@type - Describe the expected type of a variable's value or the value returned by a function.
@version - Indicate the release version of this code.
一个比较全的jsdoc示例
/** * @fileoverview 文件上传队列列表显示和处理 * @author 水车 **/ KISSY.add('gallery/form/1.3/uploader/queue', function (S, Node, Base) { var EMPTY = '', $ = Node.all, LOG_PREFIX = '[uploader-queue]:'; /** * @name Queue * @class 文件上传队列,用于存储文件数据 * @constructor * @extends Base * @param {Object} config Queue没有必写的配置 * @param {Uploader} config.uploader Uploader的实例 * @example * S.use('gallery/form/1.3/uploader/queue/base,gallery/form/1.3/uploader/themes/default/style.css', function (S, Queue) { * var queue = new Queue(); * queue.render(); * }) */ function Queue(config) { var self = this; //调用父类构造函数 Queue.superclass.constructor.call(self, config); } S.mix(Queue, /**@lends Queue*/ { /** * TODO:多余? * 模板 */ tpl:{ DEFAULT:'<li id="queue-file-{id}" class="clearfix" data-name="{name}">' + '<div class="f-l sprite file-icon"></div>' + '<div class="f-l">{name}</div>' + '<div class="f-l file-status J_FileStatus"></div>' + '</li>' }, /** * 支持的事件 */ event:{ //添加完文件后触发 ADD:'add', //批量添加文件后触发 ADD_FILES:'addFiles', //删除文件后触发 REMOVE:'remove', //清理队列所有的文件后触发 CLEAR:'clear', //当改变文件状态后触发 FILE_STATUS : 'statusChange', //更新文件数据后触发 UPDATE_FILE : 'updateFile', // 恢复文件后触发 RESTORE: 'restore' }, /** * 文件的状态 */ status:{ WAITING : 'waiting', START : 'start', PROGRESS : 'progress', SUCCESS : 'success', CANCEL : 'cancel', ERROR : 'error', RESTORE: 'restore' }, //样式 cls:{ QUEUE:'ks-uploader-queue' }, hook:{ //状态 STATUS:'.J_FileStatus' }, FILE_ID_PREFIX:'file-' }); /** * @name Queue#add * @desc 添加完文件后触发 * @event * @param {Number} ev.index 文件在队列中的索引值 * @param {Object} ev.file 文件数据 */ /** * @name Queue#addFiles * @desc 批量添加文件后触发 * @event * @param {Array} ev.files 添加后的文件数据集合 */ /** * @name Queue#remove * @desc 删除文件后触发 * @event * @param {Number} ev.index 文件在队列中的索引值 * @param {Object} ev.file 文件数据 */ /** * @name Queue#clear * @desc 清理队列所有的文件后触发 * @event */ /** * @name Queue#statusChange * @desc 当改变文件状态后触发 * @event * @param {Number} ev.index 文件在队列中的索引值 * @param {String} ev.status 文件状态 */ /** * @name Queue#updateFile * @desc 更新文件数据后触发 * @event * @param {Number} ev.index 文件在队列中的索引值 * @param {Object} ev.file 文件数据 */ /** * @name Queue#restore * @desc 恢复文件后触发 * @event * @param {Array} ev.files 文件数据集合 */ //继承于Base,属性getter和setter委托于Base处理 S.extend(Queue, Base, /** @lends Queue.prototype*/{ /** * 向上传队列添加文件 * @param {Object | Array} files 文件数据,传递数组时为批量添加 * @example * //测试文件数据 var testFile = {'name':'test.jpg', 'size':2000, 'input':{}, 'file':{'name':'test.jpg', 'type':'image/jpeg', 'size':2000} }; //向队列添加文件 queue.add(testFile); */ add:function (files, callback) { var self = this,fileData={}; //如果存在多个文件,需要批量添加文件 if (files.length > 0) { fileData=[]; S.each(files,function(file){ fileData.push(self._addFile(file)); }); } else { fileData = self._addFile(files); } callback && callback.call(self); return fileData; }, /** * 向队列添加单个文件 * @param {Object} file 文件数据 * @param {Function} callback 添加完成后执行的回调函数 * @return {Object} 文件数据对象 */ _addFile:function (file,callback) { if (!S.isObject(file)) { S.log(LOG_PREFIX + '_addFile()参数file不合法!'); return false; } var self = this, //设置文件对象 fileData = self._setAddFileData(file), //文件索引 index = self.getFileIndex(fileData.id), fnAdd = self.get('fnAdd'); //执行用户自定义的回调函数 if(S.isFunction(fnAdd)){ fileData = fnAdd(index,fileData); } self.fire(Queue.event.ADD, {index:index, file:fileData,uploader:self.get('uploader')}); callback && callback.call(self, index, fileData); return fileData; }, /** * 删除队列中指定id的文件 * @param {Number} indexOrFileId 文件数组索引或文件id * @param {Function} callback 删除元素后执行的回调函数 * @example * queue.remove(0); */ remove:function (indexOrFileId, callback) { var self = this, files = self.get('files'), file; //参数是字符串,说明是文件id,先获取对应文件数组的索引 if (S.isString(indexOrFileId)) { indexOrFileId = self.getFileIndex(indexOrFileId); } //文件数据对象 file = files[indexOrFileId]; if (!S.isObject(file)) { S.log(LOG_PREFIX + 'remove()不存在index为' + indexOrFileId + '的文件数据'); return false; } //将该id的文件过滤掉 files = S.filter(files, function (file, i) { return i !== indexOrFileId; }); self.set('files', files); self.fire(Queue.event.REMOVE, {index:indexOrFileId, file:file}); callback && callback.call(self,indexOrFileId, file); return file; }, /** * 清理队列 */ clear:function () { var self = this, files; _remove(); //移除元素 function _remove() { files = self.get('files'); if (!files.length) { self.fire(Queue.event.CLEAR); return false; } self.remove(0, function () { _remove(); }); } }, /** * 获取或设置文件状态,默认的主题共有以下文件状态:'waiting'、'start'、'progress'、'success'、'cancel'、'error' ,每种状态的dom情况都不同,刷新文件状态时候同时刷新状态容器类下的DOM节点内容。 * @param {Number} index 文件数组的索引值 * @param {String} status 文件状态 * @return {Object} * @example * queue.fileStatus(0, 'success'); */ fileStatus:function (index, status, args) { if (!S.isNumber(index)) return false; var self = this, file = self.getFile(index), theme = self.get('theme'), curStatus,statusMethod; if (!file) return false; //状态 curStatus = file['status']; if(!status){ return curStatus; } //状态一直直接返回 if(curStatus == status) return self; //更新状态 self.updateFile(index,{status:status}); statusMethod = '_'+status+'Handler'; //如果主题存在对应的状态变更监听器,予以执行 if(theme && S.isFunction(theme[statusMethod])){ args = S.merge({uploader:self.get('uploader'),index:index,file:file,id:file.id},args); theme[statusMethod].call(theme,args); } self.fire(Queue.event.FILE_STATUS,{index : index,status : status,args:args,file:file}); return self; }, /** * 获取指定索引值的队列中的文件 * @param {Number} index 文件在队列中的索引 * @return {Object} */ getFile:function (index) { if (!S.isNumber(index)) return false; var self = this, files = self.get('files'), file = files[index]; if (!S.isPlainObject(file)){ S.log('getFile():文件数据为空!'); file = {}; } return file; }, /** * 根据文件id来查找文件在队列中的索引 * @param {String} fileId 文件id * @return {Number} index */ getFileIndex:function (fileId) { var self = this, files = self.get('files'), index = -1; S.each(files, function (file, i) { if (file.id == fileId) { index = i; return true; } }); return index; }, /** * 更新文件数据对象,你可以追加数据 * @param {Number} index 文件数组内的索引值 * @param {Object} data 数据 * @return {Object} */ updateFile:function (index, data) { if (!S.isNumber(index)) return false; if (!S.isObject(data)) { S.log(LOG_PREFIX + 'updateFile()的data参数有误!'); return false; } var self = this, files = self.get('files'), file = self.getFile(index); if (!file) return false; S.mix(file, data); files[index] = file; self.set('files', files); self.fire(Queue.event.UPDATE_FILE,{index : index, file : file}); return file; }, /** * 获取等指定状态的文件对应的文件数组index的数组 * @param {String} type 状态类型 * @return {Array} * @example * //getFiles()和getFileIds()的作用是不同的,getFiles()类似过滤数组,获取的是指定状态的文件数据,而getFileIds()只是获取指定状态下的文件对应的在文件数组内的索引值。 * var indexs = queue.getFileIds('waiting'); */ getIndexs:function (type) { var self = this, files = self.get('files'), status, indexs = []; if (!files.length) return indexs; S.each(files, function (file, index) { if (S.isObject(file)) { status = file.status; //文件状态 if (status == type) { indexs.push(index); } } }); return indexs; }, /** * 获取指定状态下的文件 * @param {String} status 状态类型 * @return {Array} * @example * //获取等待中的所有文件 * var files = queue.getFiles('waiting'); */ getFiles:function (status) { var self = this, files = self.get('files'), statusFiles = []; if (!files.length) return []; S.each(files, function (file) { if (file && file.status == status) statusFiles.push(file); }); return statusFiles; }, /** * 添加文件时先向文件数据对象追加id、size等数据 * @param {Object} file 文件数据对象 * @return {Object} 新的文件数据对象 */ _setAddFileData:function (file) { var self = this, files = self.get('files'); if (!S.isObject(file)) { S.log(LOG_PREFIX + '_updateFileData()参数file不合法!'); return false; } //设置文件唯一id if (!file.id) file.id = S.guid(Queue.FILE_ID_PREFIX); //转换文件大小单位为(kb和mb) if (file.size && S.convertByteSize) file.textSize = S.convertByteSize(file.size); //状态 file.status = EMPTY; files.push(file); return file; } }, {ATTRS:/** @lends Queue.prototype*/{ /** * 添加完文件数据后执行的回调函数,会在add事件前触发 * @type Function * @default '' */ fnAdd:{value:EMPTY}, /** * 队列内所有文件数据集合 * @type Array * @default [] * @example * var ids = [], files = queue.get('files'); S.each(files, function (file) { ids.push(file.id); }); alert('所有文件id:' + ids); */ files:{value:[]}, /** * 该队列对应的Uploader实例 * @type Uploader * @default "" */ uploader:{value:EMPTY}, /** * 主题实例 * @type Theme * @default "" */ theme:{value:EMPTY} }}); return Queue; }, {requires:['node', 'base']});
View Code
命令名描述
@param @argument 指定参数名和说明来描述一个函数参数
@returns 描述函数的返回值
@author 指示代码的作者
@deprecated 指示一个函数已经废弃,而且在将来的代码版本中将彻底删除。要避免使用这段代码
@see 创建一个HTML链接,指向指定类的描述
@version 指定发布版本
@requires 创建一个HTML链接,指向这个类所需的指定类
@throws @exception 描述函数可能抛出的异常的类型
{@link} 创建一个HTML链接,指向指定的类。这与@see很类似,但{@link}能嵌在注释文本中
@fileoverview(@file || @overview) 这是一个特殊的标记。如果在文件的第一个文档块中使用这个标记,则指定该文档块的余下部分将用来提供这个文件的概述
@class 提供类的有关信息,用在构造函数的文档中
@constructor 明确一个函数是某个类的构造函数
@type 指定函数的返回类型
@extends 指示一个类派生了另一个类。JSDoc通常自己就可以检测出这种信息,不过,在某些情况下则必须使用这个标记
@private 指示一个类或函数是私有的。私有类和函数不会出现在HTML文档中,除非运行JSDoc时提供了--private命令行选项
@final 指示一个值是常量值。要记住JavaScript无法真正保证一个值是常量
@ignore JSDoc忽略有这个标记的函数
@method == @func == @function 将这个函数定义为global下的methods类下
@function functionName == @func + @name functionName
@member 该
paginate对象将被记录为一个通用的对象
官方文档
@augments - Indicate this class uses another class as its "base."
@author - Indicate the author of the code being documented.
@argument - Deprecated synonym for @param.
@borrows that as this - Document that class's member as if it were a member of this class.
@class - Provide a description of the class (versus the constructor).
@constant - Indicate that a variable's value is a constant.
@constructor - Identify a function is a constructor.
@constructs - Identicate that a lent function will be used as a constructor.
@default - Describe the default value of a variable.
@deprecated - Indicate use of a variable is no longer supported.
@description - Provide a description (synonym for an untagged first-line).
@event - Describe an event handled by a class.
@example - Provide a small code example, illustrating usage.
@extends - Synonym for @augments.
@field - Indicate that the variable refers to a non-function.
@fileOverview - Provides information about the entire file.
@function - Indicate that the variable refers to a function.
@ignore - Indicate JsDoc Toolkit should ignore the variable.
@inner - Indicate that the variable refers to an inner function (and so is also @private).
@lends - Document that all an object literal's members are members of a given class.
{@link ...} - Like @see but can be used within the text of other tags.
@memberOf - Document that this variable refers to a member of a given class.
@name - Force JsDoc Toolkit to ignore the surrounding code and use the given variable name instead.
@namespace - Document an object literal is being used as a "namespace."
@param - Describe a function's parameter.
@private - Indicate a variable is private (use the -p command line option to include these).
@property - Document a property of a class from within the constructor's doclet.
@public - Indicate an inner variable is public.
@requires - Describe a required resource.
@returns - Describe the return value of a function.
@see - Describe a related resource.
@since - Indicate that a feature has only been available on and after a certain version number.
@static - Indicate that accessing the variable does not require instantiation of its parent.
@throws - Describe the exception that a function might throw.
@type - Describe the expected type of a variable's value or the value returned by a function.
@version - Indicate the release version of this code.
相关文章推荐
- 如何将jsp页面的table报表转换到excel报表导出
- JSP学习笔记(第2次):Servlet过滤器
- js总结高级
- javascriptTable排序
- 史上最详细的javascript闭包(Closure)说明
- 关于与同学合作的 排序算法显示小应用 的个人总结
- js判断手机,邮箱格式是否正确
- 【BZOJ-2725】故乡的梦 Dijsktra + Tarjan + Dinic + BFS + 堆
- Eclipse去除js(JavaScript)验证错误
- js判断undefined类型
- 如何利用正则表达式限制输入0到100的数(js)
- JavaScript多行字符串
- chrome 控制台js调试与断点调试
- 数组去重整理
- js实现div的显示与隐藏
- 用原生js统计文本行数的简单示例
- 实现页面跳转后,原页面弹窗且不让后页面失去焦点-javascript函数执行顺序问题
- 如何正确理解和使用ES6 Promise?(We have a problem with promises)
- 使用动态脚本元素加载js
- Javascript详解一