# JSDOC 常用标记

# 1. 介绍

JS DOC 常用标签

# 2. 标签

# 2.1. @param

说明：

标记提供函数、方法参数的名称、类型和描述

语法：

@param [<type>] <name> [<description>]

基本使用：

/**
 * 可以在变量说明前加个连字符，使之更加容易阅读
 * 
 * @param {string} name  Somebody's name.
 * @param {number} age - Somebody's age.
 */
function sayHello(name, age) {
  // ...
}

对象类型，标记属性类型：

/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
function(employee) {
  // ...
};

数组类型，标记条目类型：

/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
function(employees) {
  // ...
};

可选参数：

/**
 * @param {string} [somebody] - Somebody's name.
 */
function sayHello(somebody) {
  // ...
}

默认值：

/**
 * @param {string} [somebody=John Doe] - Somebody's name.
 */
function sayHello(somebody) {
  // ...
}

多种类型（联合类型）：

/**
 * @param {(string|string[])} somebody - Somebody's name, or an array of names.
 */
function sayHello(somebody) {
  // ...
}

允许任何类型：

/**
 * @param {*} somebody - Whatever you want.
 */
function sayHello(somebody) {
  // ...
}

可变数量的参数：

/**
 * Returns the sum of all numbers passed to the function.
 * @param {...number} num - A positive or negative number.
 */
function sum(num) {
  var i = 0, n = arguments.length, t = 0;
  for (; i < n; i++) {
    t += arguments[i];
  }
  return t;
}

回调函数参数：

/**
 * This callback type is called `requestCallback` and is displayed as a global symbol.
 *
 * @callback requestCallback
 * @param {number} code
 * @param {string} message
 * @param {*} data
 */

/**
 * Does something asynchronously and executes the callback on completion.
 * @param {string} url - request url
 * @param {requestCallback} cb - The callback that handles the response.
 */
function request(url, cb) {
  // ...
};

# 2.2. @return

说明：

标记记录函数返回的值
别名 @returns

语法：

@return [{type}] [description]

基本使用：

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @param {boolean} retArr If set to true, the function will return an array
 * @returns {(number|Array)} Sum of a and b or an array that contains a, b and the sum of a and b.
 */
function sum(a, b, retArr) {
  if (retArr) {
    return [a, b, a + b];
  }
  return a + b;
}

# 2.3. @type

说明：

通常用于标记变量的类型

语法：

@type {typeName}

基本使用：

/** @type {(string|Array)} */
var foo;


/** @type {number} */
var bar = 1;

类型定义：

/**
 * @typedef PropertiesHash
 * @type {object}
 * @property {string} id - an ID.
 * @property {string} name - your name.
 * @property {number} age - your age.
 */

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

# 2.4. @typedef

说明：

该标签描述自定义类型，可以在其他标签（如@param、@type）重复使用

语法：

@typedef [<type>] <namepath>

基本使用：

/**
 * A number, or a string containing a number.
 * @typedef {(number|string)} NumberLike
 */

/**
 * Set the magic number.
 * @param {NumberLike} x - The magic number.
 */
function setMagicNumber(x) {
}

复杂类型：

/**
 * request config type
 * @typedef {object} RequestConfig
 * @property {string} url - URL
 * @property {('GET' | 'POST')} method - 请求方法
 * @property {object} data - 数据
 */

/**
 * ajax request
 * @param {RequestConfig} config - request config.
 */
function request(config) {
}

# 2.5. @property

说明：

标记类、命名空间、对象的静态属性
别名 @prop

语法：

@property <type> <name> [<description>]

基本使用：

/**
 * @namespace
 * @property {object}  defaults               - The default values for parties.
 * @property {number}  defaults.players       - The default number of players.
 * @property {string}  defaults.level         - The default level for the party.
 * @property {object}  defaults.treasure      - The default treasure.
 * @property {number}  defaults.treasure.gold - How much gold the party starts with.
 */
var config = {
  defaults: {
    players: 1,
    level:   'beginner',
    treasure: {
      gold: 0
    }
  }
};

可选属性：

/**
 * User type definition
 * @typedef {Object} User
 * @property {string} email
 * @property {string} [nickName]
 */

# 2.6. @example

说明：

使用示例，显示为代码
一个文档注释中，可使用多个 @example
标签后面可以添加 <caption></caption> 标签作为示例的标题。

基本使用：

/**
 * get sum.
 * 
 * @example <caption>Example1 usage of sum.</caption>
 * 
 * sum(1, 1); // 2
 * 
 * @example <caption>Example2 usage of sum.</caption>
 * 
 * sum(1, 2); // 3
 * 
 * 
 * @returns {Number} - returns sum of a and b.
 */
function sum(a, b) {
  return a + b;
};

# 2.7. @deprecated

说明：

标记已被弃用

语法：

@deprecated [<some text>]

基本使用：

/**
 * @deprecated since version 2.0
 */
function old() {}

# 3. 参考

JSDoc 中文文档 (opens new window)

本章目录