注释规范

本文的文档是jsdoc-ci分析注释生成的文档。如果想要接入此文档，需按照以下规范添加函数注释。jsdoc-ci仅支持js文件，如果是ts文件需要现将ts文件转化为js文件。

文件注释

每个函数文件头部需要加上注释

/**
 * @desc: 埋点上报            // @desc-文件函数的注释
 * @module: report           // @module-该文件的模块名称，如果不填写，默认取文件名，后续会作为文档的导航栏
 * @private: true            // @private-私有文件，添加此标志，此文件不生成文档
 */

函数注释

/**
 * @desc 新埋点，埋点需要立即上报，不依赖用户位置                // @desc-描述
 * @private                                               // @private-私有的，添加此标志，此函数不生成文档
 * @param {object} [setting] 以下是setting的解释            // @param-参数，{object} 类型,  setting参数名，参数名添加[], [setting]此参数是可选的,非必填
 * @param {number} setting.traceSource 请求来源            // @param-参数，setting.traceSource 表示traceSource是setting对象的子项
 * @param {string} setting.subMchId 商户id
 * @param {string} appId = '123456' 小程序appid            // @param-参数，appId = '123456', '123456'appId默认值
 * @returns {Object} data    导航栏布局信息                 // @returns-返回值 {object} 类型，data返回值字段名
 * @returns {number} data.enable 是否支持自定义导航栏        // @returns-返回值 data.enable 表示enable是data对象额子集
 * @returns {number} data.menuTop 菜单按钮上边距，单位rpx
 * @example                                               // @example-函数示例
 * const { tms } = getApp({ allowDefault: true });
 * const reporter = tms.getReporter();
 * reporter.fastReport('user_security_level', {}, {});
 */
const fastReport = (setting) => {
  ...函数处理
  return data
}

class注释

/**
 * @class TMSBridge                                       // @class 类名
 */
class TMSBridge {

  /**
    * @desc 默认位置信息                                     // 属性注释
    * @property {object} locForNoAuth 默认的位置信息
    * @property {string} locForNoAuth.privince 省份信息
    * @property {string} locForNoAuth.cityCode 城市编码
    * @property {string} locForNoAuth.cityName 城市名称
    * @property {string} locForNoAuth.longitude 
  */
  locForNoAuth = {
    province: '广东省',
    cityCode: '440300',
    cityName: '深圳市',
  };

  // @private                                             // @private 类的私有函数，该函数不生成文档       
  static get navPageMap() {
    ...
  }

  /**
   * @desc choosePassenger 方法 插件调用主程序获取出行人信息
   * @param {object} setting 配置信息(以下是setting的详解)
   * @param {string} setting.picktype 选择方式：选择单个人 single， 选择多个人 multiple
   * @param {function} setting.complete 选择出行人信息后，返回时获取数据
   * @param {object} setting.complete.callback 以下回调函数的入参详解
   * @param {string} setting.complete.callback.name 姓名
   * @returns {void} 无返回值
   * @example
    this.TMSBridge.choosePassenger({
      complete: ({ list }) => {
        // console.log("passenger", list);
      },
    });
   */
  choosePassenger(setting) {
    ...
  }
}

对象注释

/** 
 * @namespace LOG                                               // @namespace 对象的字段名
 * @desc 普通日志管理器，将日志记录在小程序日志文件中                  // @desc 对象解释
 */
const LOG = {
  /**
   * @desc 写info日志
   * @param  {...Any} params 需要打印的数据，支持任意多个
   * @returns {Void} 无返回值
   */
  info(...params) {
    getLogInstance().info(...format(params));
  },
};

变量注释

/**
 * @var {object}
 * @desc 变量定义
 * @property {string} json 属性 name 用户姓名
 * @property {string} 30   属性 age 用户年龄
 */
var userInfo = {
    name: 'json',
    age: '30'
}

常量注释

/**
 * @constant {string}
 * @default #DDD  // @default-如果有默认值增加@default属性
 * @desc 常量定义
 */
const COLOR_THEME = '#DDD';

其他注释规范详见jsdoc (opens new window)