Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JSDoc #169

Open
whizbz11 opened this issue Feb 27, 2017 · 0 comments
Open

JSDoc #169

whizbz11 opened this issue Feb 27, 2017 · 0 comments

Comments

@whizbz11
Copy link
Member

什么是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;
      }
    
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant