jsdoc笔记

date: 2018.05.25; modification:2020.03.18

目录:

1 常用注释

1.1 函数

函数参数, 别名arg, argument : @param {string} name 描述
多种类型                    : @param {string|number} name 描述
重复使用的参数              : @param {...number} num
可选参数                    : @param {string=} n 或 @param {string} [n]
可选参数的默认值            : @param {string} [name = 123]

函数返回值                  : @returns {string} 描述    (别名return)
                              @returns {undefined}  无返回值(或者不写@returns项, 也表示无返回值)
                              @return {Promise<string[]>} n

函数异常                    : @throws {FooException}

函数内联注释(匿名函数)      : numbers.map((/** @type number */ n) => {
                                  return n * 2
                              })
函数内联注释2(返回值):
    function getPerson(/**String*/ name) /**Object*/ { }

例如:

定义函数原型:
    /**
     * My function
     *
     * @param {string} a
     * @param {number} b
     * @param {Object.<string, number>} c
     * @param {LifeImportant} d
     * @returns {string}
     */
    function myFunc(a, b, c, d) {
    }

1.2 类与对象

构造函数与属性: 
    /**
     * @constructor
     * @property {string} name The name of the person.
     */
    function Person(name) {
        this.name = name;
    }


对象定义:
    /**
     * A song
     * @typedef {object} Song
     * @property {string} title - The title
     * @property {string} artist - The artist
     * @property {number} year - The year
     */

简单对象定义:
    /**
     * ...
     * @returns {{version:string, major:string, minor:string, patch:string}}
     */

定义枚举:
    /**
     * Enum for life important things.
     * @readonly
     * @enum {string}
     */
    const LifeImportant = {
        EAT  : 'eat',
        SLEEP: 'sleep',
        DOTA : 'dota',
    };

1.3 其他

记录一个静态成员: @static

指明作者: @author 作者名字 <111111111@qq.com>

指明这是一个回调函数, 可传递给其他函数: @callback fuc

指明需要使用new关键字调用, 别名@constructor: @class

为类添加一大段描述: @classdesc 类描述

记录一个对象为一个常量: @constant [ ]

指明版权信息: @copyright

记录默认值, 使用该标签以后会自动添加到文档: @default []

提供一般描述, 如果在注释开始的地方添加描述, 那么可省略该标签: @description

描述一个相关属性的集合: @enum []

提供一个如何使用描述项的例子: @examples

标识一个模块: @exports moduleName

标记一个对象为一个函数: @function name

指明一个全局对象: @global

指明继承自哪个父类: @augments parent

记录一个实例成员: @instance

标识代码采用何种软件许可协议: @license

记录一个成员: @member [] []

记录一个JavaScript模块: @module

记录一个命名空间: @namespace

指明一个标识符覆盖其父类同名标识符: @override

this关键字的指向: @this

描述版本信息: @version

2 参考资料

http://www.css88.com/doc/jsdoc/index.html Type annotations in JavaScript files Type Safe JavaScript with JSDoc