JSDoc

@whizbz11 2017-02-27 01:50:13发表于 iuap-design/blog

什么是JSDoc

JSDoc是一个根据javascript文件中注释信息,生成JavaScript应用程序或库、模块的API文档 的工具。你可以使用他记录如:命名空间,类,方法,方法参数等。

使用JSDoc

JSDoc本质是代码注释,所以使用起来非常方便,但是他有一定的格式和规则,只要了解这些,那么后面的事情,比如生产文档,生成智能提示都可以通过工具来完成。如何在开发工具里自动添加注释请参考这里

JSDoc注释一般应该放置在方法或函数声明之前,它必须以/ **开始,以便由JSDoc解析器识别。其他任何以/*,/***或者超过3个星号的注释,都将被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;
    }
};

JSDoc注释标签

看了上面的代码注释是不是一目了然呢,获取你会疑惑上面以@开头的标签是什么意思。 在JSDoc 注释有一套标准的注释标签,一般以@开头。更多标签信息可以参考这里。下面列举一些常用的标签

  • @constructor 构造函数

      /**
       * Represents a book.
       * @constructor
       * @param {string} title - The title of the book.
       * @param {string} author - The author of the book.
       */
      function Book(title, author) {
      }
    
  • @param 用来描述一个方法参数的名字、类型、具体含义

      /**
       * @param {string} somebody Somebody's name.
       */
      function sayHello(somebody) {
          alert('Hello ' + somebody);
      }
    
  • @type 用来解释变量是什么类型。这里的类型可以是JS常用类型(number、string、boolean、object、function、Array),也可以是某个实例化的对象(myNamespace.MyClass)。

      /** @type {(string|Array.)} */ 字符串或者数组
      var foo;
      /** @type {number} */
      var bar = 1;
      /** @type {MyClass[]}*/ MyClass类型的数组
    
  • @return 一个方法的返回值

      返回某个类型
      /**
       * 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;
      }
    
  • @namespace 标识一个对象为其成员创建命名空间。

      /**
       * Mynamespace.
       * @namespace
       */
      var MyNamespace = {
          /** documented as MyNamespace.foo */
          foo: function() {},
          /** documented as MyNamespace.bar */
          bar: 1
      };
    
  • @description 具体的描述

      /**
       * @param {number} a
       * @param {number} b
       * @returns {number}
       * @description Add two numbers.
       */
      function add(a, b) {
          return a + b;
      }