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

前言:

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

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

作者:段旭文
来源:CSDN
原文:https://blog.csdn.net/qq_33538554/article/details/93616470
版权声明:本文为博主原创文章,转载请附上博文链接!

你可能感兴趣的:(前端开发)