介绍
作用
- 合作分享：方便他人阅读，便于分享
- 沉淀总结：容易忘记代码，总结沉淀
形式
- // 双斜杠
- /**/ 斜杠星号
常用标签
| 标签 | 描述 |
|---|---|
| @module 1 | 标明当前文件模块，在这个文件中的所有成员将被默认为属于此模块，除非另外标明 |
| @submodule 1 | 针对模块的划分，处于@module之下 |
| @class | 标示一个类或一个函数 |
| @constructor | 当使用对象字面量形式定义类时，可使用此标签标明构造函数 |
| @callback | 标明此方法是一个回调函数 |
| @event | 标明一个可触发的事件函数，一个典型的事件是由对象定义的一组属性来标示。 |
| @constant | 常量标识 |
| @member/@var | 记录一个基本数据类型的成员变量 |
| @method | 标记一个方法或函数 |
| @param | 标记方法参数及参数类型 |
| @property | 标明一个对象属性 |
| @readonly | 只读 |
| @return | 标明返回值、类型及描述 |
| @type | 描述代码变量的类型 |
| @description | 如果在注释开始描述可省略此标签 |
| @enum | 一个类中属性的类型相同，使用此标签标明 |
| @example | 示例，代码可自动高了 |
| @exports | 标识此对象将会被导出到外部调用 |
| @ignore | 忽略此注释 |
| @link | 内联标签，创建一个标签。如'{@link http://github.com Github}’ |
| @name | 指定一段代码的名字，强制JsDoc使用此名称，而不是代码里的名称 |
| @namespace | 指定一个变量命名空间变量 |
| @static | 描述一个不需实例即可使用的变量 |
| @summary | 对描述信息的短的概述 |
| @throws | 描述方法将会出现的错误和异常 |
| @todo | 描述函数的功能和任务 |
| @tutorial | 插入一个指向向导教程的链接 |
| @see | 标签允许您引用可能与被记录的相关的另一个符号或资源 |
开发工具
sublime+DocBlockr
/** Tab(回车)自动生成注释
在注释中回车自动生成 *
输入@会自动提示标准注释的标签
文档输出
YUIDoc
不解析文本，完全按照注释标签进行生成文档，与代码分离
NodeJs环境
安装YUIDoc
npm install –g yuidocjs使用
- 在相应的目录下输入 yuidoc . ，会在当前目录生成 out文件，里面生成注释文档
- 在相应的目录下输入 yuidoc . –server <port>，会使用nodejs环境生成对应的网站
更多标签可参考：
编写Js注释
- 以 /* 开头，/ 结束
- 按照层级格式编写：@module,[@sumodule],@class,@method,@property等层级格式
- @method，@property，@param等必须在@class下面
- 每个标签快里面只能包含下面一个标签，描述了当前代码块的作用。
- @module 标签描述一组关联的类（对于JS 没有类，YUIDoc只是把有构造方法也归为类罢了）。
- @class标签专门描述类的。在YUI库中通常是个构造函数。每个有@class 标签的注释块都应该有一个@static 或者 @constructor的副标签。
- @method 描述类中的方法。你将会用到 @return 和 @params 副标签加以说明。
- @property 描述类中的属性
- @event 描述你自定义的可触发事件。YUIDoc文档里指出
