前言

有良好的注释，在 VSCode 这样的编辑器里，会有良好的提示，更加便于阅读与使用。
注释中的类型说明，推荐使用大写字符（参考 vue 的格式），例如：字符串 - String。

普通注释

需要添加方法说明，参数的类型及其说明，返回数据的类型及其说明

  1. /**
  2.  * 获取数据的相关方法
  3.  * 
  4.  * @param {String} str 需要处理的数据
  5.  * 
  6.  * @returns {String} 处理空数据后的结果
  7.  */
  8. function getData(str) {
  9.     return str ? str : "空";
  10. }

数组注释

添加数据类型:

  • 不确定类型数组 - Array
  • 确定类型数组，应该加上对应的数据类型 - Array、Array、Array 
    1. /**
    2.  * 检查数组
    3.  * 
    4.  * @param {Array} arr 
    5.  * @param {String} value 
    6.  */
    7. let checkArray = (arr, value) => {
    8.     // ...
    9. }

    对象注释

    一个对象会带有多个属性，可以同时在注释添加子属性的说明

    1. /**
    2.  * 设置配置项
    3.  * 
    4.  * @param {Object} cfg 配置项
    5.  * @param {String} cfg.key 普通项
    6.  * @param {Object} cfg.wx 第二级配置项
    7.  * @param {String} cfg.wx.appId 第三级的说明
    8.  */
    9. let setCfg = (cfg) => {
    10.     // ...
    11. }

    可为空注释

    如果一个值可以为空值，需要对该注释添加[]

    1. /**
    2.  * 设置配置项
    3.  * 
    4.  * @param {String} key 不可为空的值
    5.  * @param {Number} [num] 可以为空的值
    6.  */
    7. let setCfg = (key, num) => {
    8.     // ...
    9. }

    类注释（class）

    • 在构建类对象的时候，必须对 constructor 方法进行注释，不然在 new 对象时，无法获取对应提示
    • 在类注释里，把可以公开访问获取的属性与方法，添加在类名注释上，便于查看有什么方法与属性可以调用
    • （类名顶部注释）可以外部访问的属性使用 @property 注释
    • （类名顶部注释）可以在外部访问的方法使用 @property 注释
    1. /**
    2.  * Test 方法类
    3.  * 
    4.  * - 在类注释里，把可以公开访问获取的属性与方法，添加在类名注释上，便于查看有什么方法与属性可以调用
    5.  * 
    6.  * @property {String} id id，方便看代码的时候查看
    7.  * @property {Number} index id
    8.  * 
    9.  * @function getData 获取数据
    10.  */
    11. class Test {
    13.     /**
    14.      * 
    15.      * @param {Object} cfg 配置项
    16.      * @param {String} cfg.id Id
    17.      * @param {Number} cfg.index 下标
    18.      */
    19.     constructor(cfg) {
    20.         // ...
    21.     }
    23.     /**
    24.      * 获取数据
    25.      * 
    26.      * @returns {object} 
    27.      */
    28.     getData() {
    29.         return {
    30.             data: '1'
    31.         };
    32.     }
    33. }