对于代码,解析器会根据注释内容提取出相应信息,形成文档页面。

现在支持的注释形式如下:

每个代码块可以用这样一个注释块。

对于方法可以使用下面注释形式:

/**
 * 打开
 *
 * @method XXX.router.open
 * @static 标识静态属性/方法
 * @alias XXX.open
 * @category Router
 * @version 1.0.0
 * @foldnumber 8 代码块折叠行数
 * @param {String} [name] 视图名 <1.0.0>
 * @returns {Object} 返回值
 * @examplelanguage js
 * @example
 * XXX.open('view', {
 *     param: {
 *         x: 1,
 *         y: 2
 *     },
 *     ani: 'moveEnter',
 * });
 * @description
 * *open* 主要用于切换视图,类似于PC端的跳转,近似于App上的切换视图操作。
 */

对于属性可以使用下面注释形式:

/**
 * iOS 设备嗅探
 *
 * @property XXX.sniff.ios
 * @type {Boolean}
 * @category Sniff
 */

每个组件的代码在一个文件内,一个包含 @component 标签的注释块为组件说明,数个包含 @property 标签的注释块为配置属性,数个包含 @method 标签的注释块为实例方法,数个包含 @event 标签的注释块为监听的事件类型。

/**
 * 滚动组件
 *
 * @component ScrollView
 * @examplelanguage js
 * @example ./Playground/js/Examples/ScrollViewExample/vertical&horizontal.js[1-77]
 * @version >=0.20.0
 * @foldnumber 8 代码块折叠行数
 * @description 一个包装了平台的ScrollView(滚动视图)的组件,同时还集成了触摸锁定的“响应者”系统。
 *
 * * 记住ScrollView必须有一个确定的高度才能正常工作,因为它实际上所做的就是将一系列不确定高度的子组件装进一个确定高度的容器(通过滚动操作)。
 * * 要给一个ScrollView确定一个高度的话,要么直接给它设置高度(不建议),要么确定所有的父容器都已经绑定了高度。
 * * 在视图栈的任意一个位置忘记使用{flex:1}都会导致错误,你可以使用元素查看器来查找问题的原因。
 *
 * ![ScrollView](./images/ScrollView.png)
 *
 *  @instructions {instruInfo: ./alert.md}{instruUrl: alert/index.html}
 */

// 配置

/**
 * 内容位移
 *
 * 滑块刻度标签
 * @property scaleFormat
 * @static
 * @type function/string
 * @param {Number} scale 单个标签对应的value值
 * @param {Number} [index] 当前标签对应的下标
 * @description 类型提示:支持数组传值;也支持用函数格式化字符串:函数有两个参数(scale, index);
 * 受控属性:滑块滑到某一刻度时所展示的刻度文本信息。如果不需要标签,请将该属性设置为 [] 空列表来覆盖默认转换函数。
 * @returns {Boolean} 是否成功
 * @default scale => scale
 * @examplelanguage js
 * @example
 * PropTypes.arrayOf(
 *     PropTypes.shape({
 *         text: PropTypes.string.isRequired,
 *         className: PropTypes.string,
 *         onTap: PropTypes.func.isRequired,
 *   })
 * )
 *
 */

// 方法

 /**
  * @method 组件关闭,无过渡动画
  * @static
  * 返回给外部的回调函数, 为swipeMenuList特制,
  * @param isClearTransition {Boolean}
  * @description 类型提示:支持数组传值;也支持用函数格式化字符串:函数有两个参数(scale, index);
  * 受控属性:滑块滑到某一刻度时所展示的刻度文本信息。如果不需要标签,请将该属性设置为 [] 空列表来覆盖默认转换函数。
  * @returns {Boolean} 是否成功
  * @examplelanguage js
  * @example
  * PropTypes.arrayOf(
  *     PropTypes.shape({
  *         text: PropTypes.string.isRequired,
  *         className: PropTypes.string,
  *         onTap: PropTypes.func.isRequired,
  *   })
  * )
  */

// 事件

  /**
   * @event onScroll
   * @static
   * @description 类型提示:支持数组传值;也支持用函数格式化字符串:函数有两个参数(scale, index);
   * @param isClearTransition {Boolean}
   * @returns {Boolean} 是否成功
   * @examplelanguage js
   * @example
   * PropTypes.arrayOf(
   *     PropTypes.shape({
   *         text: PropTypes.string.isRequired,
   *         className: PropTypes.string,
   *         onTap: PropTypes.func.isRequired,
   *   })
   * )
   */

每个代码块可以用这样一个注释块。

对于方法可以使用下面注释形式:

/**
 * 注释头部可以直接编写描述
 *
 * @interface /qhot/v2/addModule  接口名称
 * @method GET 请求的方法
 * @category 接口分类
 * @foldnumber 3 需要在配置文件中配置foldnumber,默认折叠6行,可以在这里自定义配置行数
 * @param {String} name name描述 <1.0.0>
 * @param  {String} [age] age描述 <1.0.0, 2.1.2>
 * @examplelanguage js
 * @example ./test.json[1-12] // 返回示例
 * @description
 * *斜体* 额外说明的描述文字
 *
 */

每个代码块可以用这样一个注释块。

/**
 * @module fragment
 * @method yo-list
 * @version 1.0.0
 * @foldnumber 8 代码块折叠行数
 * @description 构造列表的自定义使用方法
 * @demo http://doyoe.github.io/Yo/demo/fragment/yo-list.html
 * @examplelanguage css
 * @example ./examples/fragment/yo-list.sccs[5-48]
 * @param {Color} $on-color 子项选中文本色 <1.4.0>
 * @param {Color} $item-bordercolor 子项边框色 <1.2.0,2.0.0>
 * @skip
 */

名称类注释 #

  • @component: 组件名
  • @module: 模块名(分类)
  • @method: 方法名
  • @property: 属性名
  • @event: 事件名
  • @interface: 接口名

标识类注释 #

  • @static: 标识静态属性/方法
  • @version: 版本

参数说明类注释 #

  • @param: 参数,格式为:{类型} [名称] 描述 (若名称以方括号包裹, 则这个参数不是必选参数)
    表述参数的版本 #
    • 从 1.0.0 开始支持: <1.0.0>
    • 在 1.0.0 添加,2.0.0版本删除: <1.0.0,2.0.0>

示例代码 #

  • @example: example 代码,文件路径[起始位置-结束位置] 或者直接写 源代码
  • @examplelanguage: 配置example的高亮语法
  • @foldnumber: 代码块折叠的行数,需要在配置文件中配置 "foldcode": true,默认6行

描述类注释 #

  • @demo: demo 地址
  • @alias: 缩略
  • @description 描述、说明
  • @returns: 返回值

其他 #

  • @category: 分类
  • @instructions: 介绍说明,格式: {instruInfo: ./xxx.md}{instruUrl: xxx.html} 前者是介绍文字,后者页面右侧会出现手机模块展示xxx.html文件
  • @skip: 跳过此注释块