vscode 编写有注解的代码插件名：koroFileHeader

最新推荐文章于 2024-08-09 08:28:45 发布

hzxOnlineOk

最新推荐文章于 2024-08-09 08:28:45 发布

阅读量1.9k

点赞数

分类专栏：前端开发

前端开发专栏收录该内容

197 篇文章 4 订阅

订阅专栏

前言：

   在敏捷开发的过程中或者说是项目后期维护的过程中，文档是必不可少的，可以避免过多的交流从而加快项目的速度，今天介绍的就是一款基于前端的工具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，生成文档的样式也可以做相应的配置或者改写，总体来说可以一用。