JSDoc常用注释标签

2017-11-30 · xiejiahe

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();
JavaScript
原创文章,转载请注明出处。