JavaScript 注释规范

JSDoc 是一个针对 JavaScript 的 API 文档生成器

注释符

块级注释

/**
 *
 */

@description

注释对象描述

/**
 * @description 注释描述
 */

@file

描述当前文件信息

/**
 * @file 文件描述
 */

@author

描述作者信息

/**
 * @author 作者信息 <邮箱>
 */

@copyright

描述版权信息

/**
 * @copyright 版权信息
 */

@license

描述许可证信息

/**
 * @license MIT
 */

@version

描述版本信息

/**
 * @version 1.0.0
 */

@see

描述参考信息

/**
 * @see 参考信息 {@link 参考信息链接}
 */

@todo

描述接下来准备做的事

/**
 * @todo 待办信息
 */

@function

描述函数信息

/**
 * @function 函数描述
 */

@type

描述类型信息

/**
 * 变量含义
 * @type {类型}
 */

/**
 * 一个字符或数字类型的变量
 * @type {(string|number)}
 */

/**
 * 类型为数字或空
 * @type {(?number)}
 */

/**
 * 类型为数字且不能为空
 * @type {(!number)}
 */

/**
 * 类型不做限制
 * @type {*}
 */

@param

描述函数参数信息

/**
 * @param {参数类型} 参数名称 参数描述
 */

/**
 * @param {number} a 数字
 * @param {number} b 数字
 */
function add(a, b) {}

/**
 * @param {number} a 数字
 * @param {number} [b=1]  数字, 默认值1
 */
function add(a, b) {}

/**
 * @param {*} param 参数不做类型限制
 */
function add(param) {}

@return

描述函数返回值信息

/**
 * 两个数字相加
 * @param {number} a 数字
 * @param {number} b 数字
 * @return {number} a + b 的结果
 */
function add(a, b) {
  return a + b;
}

@example

描述示例

/**
 * 两个数字相加
 * @param {number} a 数字
 * @param {number} b 数字
 * @return {number} a + b 的结果
 *
 * @example
 * add(1, 2) // 3
 */
function add(a, b) {
  return a + b;
}

@class

描述类信息

/**
 * 描述类信息
 * @class
 */

class Person {}