2018-12-17

JS的注释

摘要：jsdoc的初步学习

一直在用JS，但是真正对JS的好多规范性的用法却缺少很多认识，像是今天说的JS的注释！！！
js注释有可能要问了，js的注释不就是/*....*/或者是//这种嘛！这种说法其实也是对的，但是往往在一些完善的代码体系中，这种注释方式和我今天说的这种注释方式是并存的。
今天就说一下另外一种代码注释方式，对于我这个初学者来说算是进阶的代码注释方式。
向我们平时用到的库和框架这些，都会遇到代码看不懂，也不理解他代码的含义是做什么的是不是有返回值或者返回的类型是什么，就像下边的这种代码👇

/**
   * Close the server.
   *
   * @param {Function} cb Callback
   * @public
*/

这种代码代表的是啥意思呢！写的这些是干什么用的呢，看着像注释，但是跟我们原来写的注释还有些不一样呢。
咱们就来讲一下，这种注释，这种注释在生成代码以后会生成一份JSDoc的文档，也就是这个js文件的所有注释信息的一个汇总，不管谁在阅读这个js文件，都可以通过阅读这个JSDoc来获取这个js库或者插件的所有注释信息，这样可以让读者或者使用者能过快速定位方法或者类以及所需要的信息。
ps：生成jsDoc是需要下载jsdoc模块进行配置生成，这个通过这个进行安装配置JSDoc中文官网,这里其实包含了所有的注释属性的解释和使用方法。

这下边是比较常用的，可以参照使用！

标签	描述
@module	标明当前文件模块，在这个文件中的所有成员将被默认为属于此模块，除非另外标明
@submodule	针对模块的划分，处于@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	插入一个指向向导教程的链接