介绍

作用

  • 合作分享:方便他人阅读,便于分享
  • 沉淀总结:容易忘记代码,总结沉淀

形式

  1. // 双斜杠
  2. /**/ 斜杠星号

常用标签

标签 描述
@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
使用
  1. 在相应的目录下输入 yuidoc . ,会在当前目录生成 out文件,里面生成注释文档
  2. 在相应的目录下输入 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文档里指出

hankblog
11 声望1 粉丝

GitHub:[链接]