JSDoc的常用注释规范

JSDoc的常用注释规范

JSDoc本质是代码注释

官网——https://jsdoc.zcopy.site/

手册网API——https://www.shouce.ren/api/view/a/13232

提交代码时注意自我review与优化。注释率保持在20%以上，重点方法、变量增加具体注释。注释遵循JSDoc格式。每个迭代末我们进行本迭代重点功能的介绍及review

JSDoc注释一般应该放置在方法或函数声明之前，它必须以/ **开始，以便由JSDoc解析器识别。

1、示例

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

      /**
      * 鼠标划过时选中的要素
      * @type {array}
      */
      this.hoveredFeatures = [];

2、命令名描述

1、@param 指定参数名和说明来描述一个函数参数，

类型描述，不分大小写，最好大写开头

类型包括——*，String、Array、Object，any、boolean、undefined、number

2、@returns 描述函数的返回值，常见值同上

3、@author 指示代码的作者

4、@see 创建一个HTML链接，指向指定类的描述

5、@version 指定发布版本

6、@type 指定函数的返回类型

3、实例

/**
* @description 减法运算
* @param {Num} num1 减数
* @param {Num} num2 被减数
* @return {Num} result 结果
*/
function minus(num1,num2){
    return num1 – num2;
}

4、注

在输入/**进行回车，打开默认JSDoc注释格式时，如果/在首行和空置两格代码不在同一竖直方向，保存代码时，JSDoc的格式会变形。

   /**
* 方法描述
* @param {*} value 参数
*/
    click(value){}

应在写/**时，提前空置2格

    /**
     * 方法描述
     *  @param {*} value 参数
     */    
    click(value){}