JSDoc 是什么?

JSDoc是Javascript源代码的标记语言（特殊格式的注释）。
JSDoc用于为JavaScript应用或库中的API生成文档。
即以特殊格式的注释来描述JavaScript应用或库中的API的作用、参数列表、返回值等特性，而后通过工具自动生成API文档。

JSDoc标签

JSDoc标签用于提供更多信息。
示例：

  • @constructor表示构造函数
  • @param表示参数
    1. /**
    2. * 表示一本书
    3. * @constructor
    4. * @param {string} title - 书的标题
    5. * @param {string} author - 书的作者
    6. */
    7. function Book(title, author) {}

    标签实示例

    来源标识

    @author / @file / @version
    1. /**
    2. * @author Jane Smith <jsmith@example.com>
    3. * @file Manages the configuration settings for the widget.
    4. * @version 1.2.3
    5. */
    6. function MyClass() {}

    访问性

    @abstract (@virtual) @access / @private / @protected / @packeg / @public / @global /@instance ```javascript /* @global / var foo = ‘hello foo’;

/ @namespace */ var BaseObject = { /

  1.  * foo is now BaseObject#foo rather than BaseObject.foo.
  2.  * @instance 成员变量
  3.  */
  4. foo: null

};

/**

  • Check whether the dairy product is solid at room temperature.
  • @abstract
  • @return {boolean} */ DairyProduct.prototype.isSolid = function() { throw new Error(‘must be implemented by subclass!’); };

/* @constructor / function Thingy() {

  1. /** @access private */
  2. var foo = 0;
  4. /** @access protected */
  5. this._bar = 1;
  7. /** @access package */
  8. this.baz = 2;
  10. /** @access public */
  11. this.pez = 3;

}

// same as…

/* @constructor / function OtherThingy() {

  1. /** @private */
  2. var foo = 0;
  4. /** @protected */
  5. this._bar = 1;
  7. /** @package */
  8. this.baz = 2;
  10. /** @public */
  11. this.pez = 3;

}

  1. **@static**<br />两种用法
  2. ```javascript
  3. /** @namespace MyNamespace */
  5. /**
  6.  * @function myFunction
  7.  * @memberof MyNamespace
  8.  * @static
  9.  */
  1. /** @module Rollerskate */
  3. /**
  4.  * The 'wheel' variable is documented as Rollerskate.wheel
  5.  * rather than Rollerskate~wheel.
  6.  * @static
  7.  */
  8. var wheel = 1;

类型标识

@enum

  1. /**
  2.  * Enum for tri-state values.
  3.  * @readonly
  4.  * @enum {number}
  5.  */
  6. var triState = {
  7.     /** The true value */
  8.     TRUE: 1,
  9.     FALSE: -1,
  10.     /** @type {boolean} */
  11.     MAYBE: true
  12. };

@property

  1. /**
  2.  * @namespace
  3.  * @property {object}  defaults               - The default values for parties.
  4.  * @property {number}  defaults.players       - The default number of players.
  5.  * @property {string}  defaults.level         - The default level for the party.
  6.  * @property {object}  defaults.treasure      - The default treasure.
  7.  * @property {number}  defaults.treasure.gold - How much gold the party starts with.
  8.  */
  9. var config = {
  10.     defaults: {
  11.         players: 1,
  12.         level:   'beginner',
  13.         treasure: {
  14.             gold: 0
  15.         }
  16.     }
  17. };

@member [] []

  1. /** @class */
  2. function Data() {
  3.     /** @member {Object} */
  4.     this.point = {};
  5. }

/* @type {myCallback} / var cb;

  1. <a name="ZpLnQ"></a>
  2. ## 不常用
  4. - [@async](https://jsdoc.app/tags-async.html) 标识异步函数
  5. - [@augments](https://jsdoc.app/tags-augments.html) 标识其他参数
  6. - [@ignore](https://jsdoc.app/tags-ignore.html)
  7. - [@kind](https://jsdoc.app/tags-kind.html)
  8. - [@type](https://jsdoc.app/tags-type.html) 类型表示案例
  9. <a name="S1AyP"></a>
  10. # 
  11. <a name="Pp3xH"></a>
  12. # 安装工具
  13. 在注释写好之后，下面我们来安装jsdoc，它的作用是从源文件中将注释提取出来并生成文档。<br />注意：JSDoc是标记语言，jsdoc是工具。
  14. <a name="cfwWN"></a>
  15. ## 安装
  16. ```javascript
  17. npm install --save-dev jsdoc
  18. # npm install -g jsdoc //全局安装

生成文档

  1. jsdoc book.js

此命令会在CWD下创建out/，并将文档置于其中。


参考：