JavaScript代码注释

杂谈

1. docco

docco 是 Backbone 作者开源的一个 js 文档生成器。

安装 

1
npm install -g docco

生成文档 

1
docco demo.js

或者自定义生成路径

1
docco demo.js -o ../docs

在同级目录下生成了 docs 文件夹，访问文件里面的 index.html 进行浏览。

文档规范

docco 的文档规范是使用 markdown风格 ,在我们 JS 文件中使用 // 加 空格来使用。

具体可参考 Backbone 源码

文档规范

  1. 头部版权说明

// 加5个 空格

1
2
3
4
5
6
//     Backbone.js 1.2.3

//     (c) 2010-2015 Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors
//     Backbone may be freely distributed under the MIT license.
//     For all details and documentation:
//     http://backbonejs.org
  1. 高亮强调
1
2
// Establish the root object, `window` (`self`) in the browser, or `global` on the server.
// We use `self` instead of `window` for `WebWorker` support.
  1. 标题
1
2
// Initial Setup
// -------------

大致与 markdown 语法相同。

相关插件工具

2. jsDoc

jsDoc 是一种标准的 js 注释规范，大部分IDE都支持或者其插件。

  1. 规范

    以/**开头以及 **/结尾

    1
    /** 这是会生成文档行内注释 **/

    或者多行注释

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    /**
    * 对话框
    * @param {string} el 对话框dom对象
    * @author tommyshao
    * @description 这里是描述
    * @example 示例内容
    *  var dialog = new Dialog();
    * @constructor
    * @return
    **/
    var Dialog = function() {
      //...
    }

    Dialog.prototype = {
      show: function() {
        /**
        * @type {Boolean}
        **/
        var isShown = false;
      }
    }

    官方文档：http://usejsdoc.org/

    gulp实现jsdoc实时预览

其他文档工具