注释使用手册

技术 评论

注释使用手册：https://jsdoc.app/

中文文档：https://jsdoc.bootcss.com/tags-inline-link.html

基本注释使用方法

  • 基本类型注释

    1
    2
    3
    4
    5
    6
    7
    /**
     * @type {string} string类型
     * @type {number} number类型
     * @type {boolean} boolean类型
     * @type {null} null类型
     * @type {undefined} undefined类型
     */

  • 可选参数区别

    注释查看效果

    1
    2
    3
    4
    5
    6
    7
    /**
     * @param {string?} test1 参数1
     * @param {string=} test2 参数2
     */
    function testDefault(test1, test2) {
        return result
    }

  • 限定可选类型

    注释查看效果

    1
    2
    3
    4
    5
    6
    /**
     * @param {string | number} test 参数1
     */
    function testDefault(test1) {
        return result
    }

对象注释

注释查看效果

  • 解构对象键值:写法一

    1
    2
    3
    // 解构对象键值:写法一
    /** @type {{id: number, name: string, age: ?number}} */
    var props1;

  • 解构对象键值:写法二

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    // 解构对象键值:写法二，可重复引用
    /**
     * @typedef PropertiesHash
     * @type {object}
     * @property {string} id - an ID.
     * @property {string} name - your name.
     * @property {number?} age - your age.
     */

    /** @type {PropertiesHash} */
    var props2;

  • 解构对象键值:写法三，已有默认值，也可重复引用

    1
    2
    3
    4
    5
    6
    7
    8
    9
    // 解构对象键值:写法三 已有默认值
    var propsTemplate = {
        id: 1,
        name: 'test',
        age: 18
    }

    /** @type {propsTemplate} */
    var props3;

函数注释

  • 参数为数组

    注释查看效果

1
2
3
4
5
6
7
8
9
10
11
/**
 * @function testObjectArray
 * @description 参数为对象数组时的注释
 * @param {object[]} params 参数
 * @param {number} params[].resourceId 数组对象的key
 * @param {number} params[].id 数组对象的key
 * @return {object[]} 返回值
 */
function testObjectArray(params) {
    return result
}

  • 参数为可选

    注释查看效果

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    /**
     * @function testChange
     * @description 参数为可选参数的注释
     * @param {number=} num
     * @param {number} default
     */
    function testSelect(num, default=1) {
        return result
    }

  • 参数为可变数量

    注释查看效果

    1
    2
    3
    4
    5
    6
    7
    8
    /**
     * @function testChange
     * @description 参数为可变数量的注释
     * @param {...number} num 参数
     */
    function testChange(num) {
        return result
    }

  • 参数为自定义对象

    注释查看效果

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    var propsTemplate = {
        id: 1,
        name: 'test',
        age: 18
    }

    /**
     * @function testObject
     * @description 参数为可变数量的注释
     * @param {propsTemplate} object 参数
     * @param {propsTemplate[]} objectArray 参数
     */
    function testObject(object,objectArray) {
        return result
    }

回调函数

注释查看效果

1
2
3
4
5
6
7
8
9
/** 此处进行回调类型定义
 * @callback myCallback
 * @param {number} x 
 * @return {number}
 */

// 此处引用类型定义
/** @type {myCallback} */
var cb;

引用其他模块

通过传参引入别的模块的实例之类的，可以通过如下的方式使用其类型，这样在vscode的提示下开发更方便。

注释查看效果
注释查看效果

1
2
3
4
5
6
7
8
9
10
11
/**
 * 声明类型
 * @typedef { import("@/components/player/playerCore").default } PlayerCoreType
 */

/**
 * 使用类型
 * @type {PlayerCoreType}
 */


罗查理前端摸鱼工程师

生命不息，摸鱼不止。