JS-ES6 jsdoc通过注解生成->更具规格的API文档

前言：

       在敏捷开发的过程中或者说是项目后期维护的过程中，文档是必不可少的，可以避免过多的交流从而加快项目的速度，今天介绍的就是一款基于前端的工具jsdoc,他能够根据代码中的注释很快生成API文档,只需要一个命令。

1.首先我这里推荐一个注释的快捷键工具，您可以在VS Code 中安装它。

 

   插件名称：koroFileHeader

   截图：

   这个插件安装好后就可以使用了，鼠标点击js方法然后按 Ctrl+Alt+T ，就会自动生成注释，更多的使用方式可以在网上自行了解。

2.接下来我们安装jsdoc,您可以打开VS Code 的终端

   输入命令：npm install jsdoc -g

3.安装好之后，你可以为你的Api函数添加注释，这时就可以使用上面的快捷键了。

  

   我这里只写了参数和返回值，您也可以按照jsdoc的标准注释规格来描述更多的内容；

   下面是我粘贴的一些jsdoc注释的关键字及说明，可以参考。

    （1）对文件进行描述
             @author —— 指定项目作者
             @copyright —— 描述版权信息
             @see —— 描述可以参考外部资源
             @version —— 描述版本信息
             @tutorial —— 插入一个指向教程的链接，作为文档的一部分
             @since —— 描述该功能哪个版本哪个时间添加进来的
             @summary —— 描述一个简写版本
             @file —— 文件说明，在文件开头使用
             @license —— 描述代码才有那种软件许可协议

     （2）标注js使用方法
             @returns —— 描述一个函数的返回值
             @param —— 描述传递给函数的参数
             @description —— 描述
             @example —— 举例
             @throws —— 描述可能会被抛出什么样的错误

     （3）开发者备注
             @deprecated —— 标注关联代码已经被弃用
             @todo —— 描述一个将要完成的任务

     （4）文件详细结构
             @abstract —— 标注该成员必须在子类中实现或重写
             @access —— 标注该成员的访问级别
             @access private > @private
             @access protected > @protected
             @access public > @public
             @augments（@extends） —— 标注这个子类继承自哪个父类，后面需要加父类名
             @class（@constructor） —— 标注该函数是一个构造函数，需要使用new来实例化 function MyClass(){}
             @constant（@const） —— 标注这个对象是一个常量
             @constructs —— 标注这个函数用来作为类的构造器
             @default —— 标注默认值
             @exports —— 标注javascript模块导出的内容
             @function（@func、@method） —— 标注该对象作为一个函数
             @global —— 标注为全局变量（对象）
             @implements —— 标注实现一个接口
             @inheritdoc —— 标注继承其父类的文档
             @inner —— 标注为其父类的内部成员
             @instance —— 标注为其父类的实例成员
             @interface —— 标注其为可以实现的接口
             @kind —— 指明标注的类型（@kind class = @class）
             @lends —— 将一个字面量对象的所有成员标记为某个类（或模块）的成员
             @memberof —— 标注成员属于哪个父级
             @mixes —— 标注该对象混入了另一个对象的所有成员
             @mixin —— 标注一个混入对象
             @module —— 将当前文档标注为一个模块
             @protected—— 标注为受保护的
             @public —— 标注为公开的
             @readonly —— 标注为只读的
             @requires —— 标注这个文件需要一个javascript模块
             @static —— 标注为静态的
             @type —— 标注类型
             @typeof —— 标注一个自定义的类型
             @this —— 描述this关键字的指向
             @alias —— 标注成员有一个别名
             @borrow —— 将另一个标识符的描述添加到当前标识符的描述
             @name —— 强制jsdoc使用这个给定的名称，而忽略代码里的实际名称
             @namespace —— 标注一个命名空间对象
             @override —— 标注覆盖其父类同名的方法
             @private —— 标注为私有
             @classdesc —— 与@class结合使用，描述类
             @callback —— 描述一个回调函数
             @enum —— 描述一个静态属性值的全部相同的集合，通常与@readonly结合使用
             @event —— 描述事件
             @member —— 描述一个成员 @member [] []
             @property —— 描述一个对象的属性
             @external —— 标识一个外部的类，命名空间，或模块
             @files —— 标明当一个方法被调用时将触发一个指定类型的事件
             @listens —— 标注监听事件
             @variation —— 区分具有相同名称的不同对象

4.当您写完注释之后，就可以在终端输入命令了，我这里说两个命令：

   单个文件生成：你需要输入命令：cd  文件夹路径【例：js文件在Project/test/mytest.js目录下，您就输入cd  Project/test 按Enter键】，然后输入jsdoc mytest.js ，这时你会发现Project目录下多了一个out文件夹，然后在浏览器打开里面的index.html，就会看到已经生成好的文档。

截图：

多个文件生成：还是和上面一样，你需要输入cd 命令，先定位到你的文件夹，比如你的test文件夹里面有多个js文件，你需要输入命令：jsdoc -r test/

这样生成的Api文档中，就会包含所有的写过注释的Api函数。没有写注释的方法函数不会生成在文档中。

注：当然了，使用jsdoc，生成文档的样式也可以做相应的配置或者改写，总体来说可以一用。

更多的知识可以在网上查找，不多说了。