JSDoc本质是代码注释
JSDoc必须以/**开头的注释方式去使用。
什么时候应该使用JSDoc ?
不一定说任何函数方法都必须使用JSDoc,但是有一点要注意如果是自己封装的方法,有必要使用JSDoc,理由是可以让其他成员更容易的去了解你封装的方法的属性或返回值,这样可以降低维护成本和提高开发效率。
@function, 别名@func / @method
用于定义当前对象是一个函数,后面可跟描述
/**
* @function 关于人的函数
*/
function people () {}
@param, 别名@arg / @argument
定义一个参数的类型,大括号是类型,后面跟着参数名, - 跟着描述
/**
* @param {Number} age - 年龄
*/
function people (age) {}
@returns 或 @return
/**
* @returns {Number} 两个数相加
*/
function sum (a, b) {
return a + b;
}
@this
this指向哪里
/**
* @this window
*/
var arr = ['hello world'];
function demo () {
return this.arr;
}
console.log(demo());
@author
@author 后面跟着作者名字,如果出现<>里面是邮件地址,会默认转成mailto:链接
/**
* @author XieJiaHe <mb06@qq.com>
*/
class People {}
@version
注明版本号,常用在文件顶部
/**
* @version 1.0.0
*/
class People {}
@constant,别名@const
指明这是一个常量不可改变,大括号注明常量类型(可选)
/**
* @constant {Number}
*/
var AGE = 11;
@file,别名 @fileoverview / @overview
用于描述一个文件
/**
* @file 这是一个用Markdown写的文章
*/
@copyright
一般配合@file使用,@copyright 跟着版权信息
/**
* @file 这是一个用Markdown写的文章
* @copyright 版权所有,转载请注明出处
*/
@license
标识代码采用何种许可证
/**
* @license Released under the MIT License.
*/
@readonly
标记为只读,跟@const 类似
/**
* @readonly
*/
const AGE = 22;
@global
标记一个变量为全局
function people () {
/** @global */
var age = 22;
this.age = age;
}
people();
console.log(age) // 22
@description, 别名@desc
用于描述
/**
* @description 点击事件触发的方法
* @func
*/
function handleClick () {}
@class
标记这是一个构造器,需要通过new关键字实例化
/**
* @class
*/
function Person () {}
var person = new Person();