JavaScript 的 API 文档生成

看公众号有一篇关于 JS 工具函数大全，心想着纳入我的博客中，又想起用过 vue-element-admin 中有个日期过滤器不错，也总结到一起，一看过滤器脚本中注释中有 @param 由此便引出了这篇博客。

JSDoc

什么是 JSDoc

JSDoc 3是用于JavaScript的API文档生成器，类似于Javadoc或phpDocumentor。您可以将代码注释直接添加到源代码中，并直接添加到源代码中。JSDoc工具将扫描您的源代码并为您生成一个HTML文档网站。
JSDoc的目的是记录您的JavaScript应用程序或库的API。假定您将要记录诸如模块，名称空间，类，方法，方法参数之类的内容。
JSDoc 注释一般应该放置在方法或函数声明之前，它必须以 / ** 开始，

使用 JSDoc

/**
 * Book类，代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book(title, author) {
  this.title = title;
  this.author = author;
}
Book.prototype = {
  /**
   * 获取书本的标题
   * @returns {string|*}
   */
  getTitle: function () {
    return this.title;
  },
  /**
   * 设置书本的页数
   * @param pageNum {number} 页数
   */
  setPageNum: function (pageNum) {
    this.pageNum = pageNum;
  },
};

块标签

@event

描述：描述一个事件。

• @fires： 表明方法可以触发该事件
• @listens 表明用这个表示来侦听该事件

示例：

/**
 * Throw a snowball.
 *
 * @fires Hurl#snowball
 */
Hurl.prototype.snowball = function () {
  /**
   * Snowball event.
   *
   * @event Hurl#snowball
   * @type {object}
   * @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
   */
  this.emit("snowball", {
    isPacked: this._snowball.isPacked,
  });
};

@external

描述:标识一个外部的类，命名空间，或模块。
别名: @host

例如，描述内置类添加方法：

/**
 * The built in string object.
 * @external String
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String|String}
 */

/**
 * Create a ROT13-encoded version of the string. Added by the `foo` package.
 * @function external:String#rot13
 * @example
 * var greeting = new String('hello world');
 * console.log( greeting.rot13() ); // uryyb jbeyq
 */

例如，描述的外部的命名空间：

/**
 * The jQuery plugin namespace.
 * @external "jQuery.fn"
 * @see {@link http://learn.jquery.com/plugins/|jQuery Plugins}
 */

/**
 * A jQuery plugin to make stars fly around your home page.
 * @function external:"jQuery.fn".starfairy
 */

例如，扩展一个外部类：

/**
 * The built-in class for sending HTTP requests.
 * @external XMLHttpRequest
 * @see https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
 */

/**
 * Extends the built-in `XMLHttpRequest` class to send data encoded with a secret key.
 * @class EncodedRequest
 * @extends external:XMLHttpRequest
 */

例如，记录一个嵌套的外部标识：

/**
 * External namespace for security-related classes.
 * @external security
 * @see http://example.org/docs/security
 */

/**
 * External class that provides Transport Layer Security (TLS) encryption.
 * @class TLS
 * @memberof external:security
 */

@module

记录一个 JavaScript 模块。

例如，如果没有提供导出模块的名称：

# from src/
jsdoc ./test.js   # module name 'test'

# from src's parent directory:
jsdoc src/test.js # module name 'src/test'
jsdoc -r src/     # module name 'test'

/** @module myModule */

// 模块私有的
/** will be module:myModule~foo */
var foo = 1;

// 由模块导出一个静态函数
/** will be module:myModule.bar */
var bar = function () {};

例如，定义导出的标识符为’this’的成员：

/** @module bookshelf */
/** @class */
this.Book = function (title) {
  /** The title. */
  this.title = title;
};

例如，定义导出的标识符为 module.exports 或 exports 的成员:

/** @module color/mixer */
module.exports = {
  /** Blend two colours together. */
  blend: function (color1, color2) {},
};
/** Darkens a color. */
exports.darken = function (color, shade) {};

@param

描述: 记录传递给一个函数的参数。
别名：

• arg
• argument

注释变量名 、 变量类型 和 变量说明，例如：

/**
 * @param {string} somebody - Somebody's name.
 */
function sayHello(somebody) {
  alert("Hello " + somebody);
}

例如，描述一个对象参数的属性：

/**
 * 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.
 */
Project.prototype.assign = 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.
 */
Project.prototype.assign = function (employees) {
  // ...
};

一个可选参数（使用 JSDoc 语法），例如：

/**
 * @param {string} [somebody] - Somebody's name.
 */
function sayHello(somebody) {
  if (!somebody) {
    somebody = "John Doe";
  }
  alert("Hello " + somebody);
}

// 选参数和默认值：
/**
 * @param {string} [somebody=John Doe] - Somebody's name.
 */
function sayHello(somebody) {
  if (!somebody) {
    somebody = "John Doe";
  }
  alert("Hello " + somebody);
}

例如，允许一个类型或另一个类型：

/**
 * @param {(string|string[])} [somebody=John Doe] - Somebody's name, or an array of names.
 */
function sayHello(somebody) {
  if (!somebody) {
    somebody = "John Doe";
  } else if (Array.isArray(somebody)) {
    somebody = somebody.join(", ");
  }
  alert("Hello " + somebody);
}

例如，允许任何类型：

/**
 * @param {*} somebody - Whatever you want.
 */
function sayHello(somebody) {
  console.log("Hello " + JSON.stringify(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} responseCode
 * @param {string} responseMessage
 */

/**
 * Does something asynchronously and executes the callback on completion.
 * @param {requestCallback} cb - The callback that handles the response.
 */
function doSomethingAsynchronously(cb) {
  // code
}

@returns

描述: 记录一个函数的返回值。

返回值的类型和描述，例如：

/**
 * Returns the sum of a and b
 * @param {Number} a
 * @param {Number} b
 * @returns {Number} Sum of a and b
 */
function sum(a, b) {
  return a + b;
}

返回值可以有不同的类型，例如：

/**
 * 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;
}

@constructs

描述: 这个函数成员将成为类的构造函数。

• @lends：将一个字面量对象的所有属性标记为某个标识符（类或模块）的成员。
• @param：标明这个标识属于哪个父级标识。

例如， @constructs 和 @lends 结合使用：

var Person = makeClass(
  /** @lends Person.prototype */
  {
    /** @constructs */
    initialize: function (name) {
      this.name = name;
    },
    /** Describe me. */
    say: function (message) {
      return this.name + " says: " + message;
    },
  }
);

不和@lends结合使用的时候，你必须提供一个类的名称:

makeClass('Menu',
    /**
     * @constructs Menu
     * @param items
     */
    function (items) { },
    {
        /** @memberof Menu# */
        show: function(){
        }
    }
);

内联标签

@link

描述: 链接到文档中的另一个项目。

别名：

• @linkcode：强制使用等宽字体链接文本。
• @linkplain：强制显示为正常的文本，没有等宽字体链接文本。

例如，提供链接文本：

/**
 * See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
 * Also, check out {@link http://www.google.com|Google} and
 * {@link https://github.com GitHub}.
 */
function myFunction() {}

@tutorial

描述: 链接到一个教程。

下面的例子显示了提供给{@tutorial}标签链接文本的所有方式，例如：

/**
 * See {@tutorial gettingstarted} and [Configuring the Dashboard]{@tutorial dashboard}.
 * For more information, see {@tutorial create|Creating a Widget} and
 * {@tutorial destroy Destroying a Widget}.
 */
function myFunction() {}

---

以上是我对下列视频及文章的归纳和总结。
JSDoc 注释规范
Js 注释
JS Doc3 + Docstrap 生成ES6规范下的JS代码的API文档
jsdoc的使用
VSCode + JSDoc 完美实现（almost）JavaScript代码提示

---

相关资料
YUIDoc 语法参考
使用 JSDoc
JSDoc 中文文档