VSCode + JSDoc 完美实现（almost）JavaScript代码提示

wslongchen 发布于2019-08-23 10:23 / 1255人阅读

摘要：的出现大有统一轻量级领域之势，在其新版本中自带了的解析功能，帮助开发者通过书写注释的形式向提供必要信息，完善提示功能。如果因为这种需求就额外的，就会破坏了代码正常的依赖关系。

弱类型脚本语言的代码提示功能一直是开发者一个隐隐的痛点，没有它也不是不能干活，但是经常因为出现拼写错误或不经意的修改导致的变量丢失而耗费无畏的时间在与业务逻辑无关的地方。VSCode的出现大有统一轻量级IDE领域之势，在其新版本中自带了JSDoc的解析功能，帮助JavaScript开发者通过书写注释的形式向IDE提供必要信息，完善提示功能。

先来看一个简单的例子（微信小程序前端代码）

export class CommonUtilsWX {
    request(o, callback){
       //TODO:xxxxx
    }
}

可以看出该函数的定义中有一个object类型的参数o和一个函数型的回调参数callback。但是单纯从代码定义中IDE无法得知对象o中必须包含那些字段、callback回调函数中会带回哪些参数。对于JavaScript等弱类型脚本语言来说不到运行时阶段这些信息是没有意义的，而对于开发者而言，这些信息在一段时间以后很容易遗忘，更别说交付给第三方使用。所以这些信息就需要用JSDoc来书写出来。

export class CommonUtilsWX {
    /**
     * 发送网络请求，通信协议必须是http或https，数据协议必须是json
     * @param {object} o 请求参数对象
     * @param {string} o.host 请求url的域名，如http://xxx.xxx.com
     * @param {string} o.path 请求url的路径，如xxx/xxx
     * @param {object} o.query 请求url的查询段，根据对象中key，value拼成key1=value1&key2=value2的形式
     * @param {string} o.method 请求方法，如GET，POST等
     * @param {object} o.body 请求数据体，仅在method为POST时有效
     * @param {function(Error):void} callback 请求回调，请求成功时error为空
     */
    request(o, callback){
        //TODO:xxxxx
    }
}

可以看出JSDoc将参数o的类型和其必要的内部构造，函数类型的参数callback将会带回的参数类型Error和返回值类型void，等信息都被清晰明确的标记出来，同时附带了文字注释。

此时，直接使用new CommonUtilsWX()构造出来的对象调用request()方法可以看到如下的提示画面

然后再向request()函数传入字面量对象时，会看到如下的提示画面

下面是第二个例子，定义一个对象，并给对象中的字段赋予JSDoc类型信息

let zy = {
    /**
     * sdk版本号
     * @type {number}
     */
    version : 0.1,

    /**
     * 分享功能管理
     * @type {Share|ShareWX}
     */
    share: Share.createAdapter(),

    /**
     * 通用工具集，如网络请求，弹框显示等
     * @type {CommonUtils}
     */
    commonUtils : CommonUtils.createAdapter(),

    /**
     * 平台功能管理，如登录，用户信息等
     * @type {Platform|PlatformWX}
     */
    platform : Platform.createAdapter(),

    /**
     * 排行榜功能管理
     * @type {Leaderboard}
     */
    leaderboard : Leaderboard.createAdapter(),

    /**
     * 广告功能管理
     * @type {Ad}
     */
    ad : Ad.createAdapter(),
}

这里面除了用到@type关键字之外，还用到在{}中“|”符号的用法。这样的用法代表所标记的字段可能是多种类型的，尤其适用于我这段代码中的情况，即一个工厂方法可能会返回属于某个父类的任何子类对象，此时如果仅使用父类类型标记这个字段，则在使用时IDE无法提示出子类中的特殊方法，所以用了多种可能的类型标记后，IDE将会把所有可能类型中的提示信息都提示出来。此时的提示信息如下图

还有另外一种方法定义一个对象中每一个字段的类型和注释，而且可以复用，看上去更为专业，那就是@typedef关键字，下面就是用@typedef关键字重新书写的zy对象的JSDoc：

/**
 * @typedef {object} ZY
 * @property {number} version sdk版本号
 * @property {Share|ShareWX} share 分享功能管理
 * @property {CommonUtils} commonUtils 通用工具集，如网络请求，弹框显示等
 * @property {Platform|PlatformWX} platform 平台功能管理，如登录，用户信息等
 * @property {Leaderboard} leaderboard 排行榜功能管理
 * @property {Ad} ad 广告功能管理
 */

/**
 * @type {ZY}
 */
let zy = {}

上半部分是用@typedef关键字定义了一个全新的类型ZY，并且把类型中的每个字段都预先定义好。然后下半部分zy对象上方用JSDoc声这个对象的类型是ZY。这种用法适合用在可以复用的类型对象上，或者其内部字段没有全部出现在字面上，或者没有集中出现在一块区域时。

下面又出现了另一个问题，VSCode是根据文件模块的依赖关系来导入其他文件中的JSDoc的，比如A.js中require("B.js")，则B.js中的JSDoc信息就可以在A.js的JSDoc中使用，也能在A.js的代码提示中显示。但偶尔会遇到一些情况，从逻辑上A.js中并不需要
require("B.js")，而在编码中却需要使用B.js文件中的JSDoc。如果因为这种需求就额外的require("B.js")，就会破坏了代码正常的依赖关系。于是就出现了如下这种用法：

/**
 * @typedef {import("B.js")} B
 */

这种方法相当于用JSDoc的方式引入的B.js文件，并将B.js中的模块定义为类型B。

最后奉上VSCode官方关于对JSDoc提示功能的支持文档地址
https://github.com/Microsoft/...
https://code.visualstudio.com...

JSDoc原本是一个为JavaScript生成文档的工具，其语法远比VSCode目前支持提示功能所用到的语法要多，有兴趣可以了解一下原生的JSDoc
http://www.css88.com/doc/jsdoc/

最后哔哔两句，入技术圈五六年来第一次发博，也是被很多资深博主的感化，发博一方面是分享自己技术方面的心得，分享过程中获得更多，一方面是提高自己书面表达能力。但入一个坑总得一步一步的入，所以先从可有可无的雕虫小技开始。

专线服务私有云 js实现提示语音 js实现输入提示 js实现搜索输入提示 almost

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/96290.html

使用JSDoc提高代码的可读性

摘要：所以编辑器就会使用一个在中经常出现用来标识任意类型的关键字来描述函数的参数以及返回值。描述类型的返回值处理现在这个年代，基本上已经普及开来，所以很多函数的返回值可能并不是结果，而是一个。工作了四年多，基本上都在围绕着 JavaScript 做事情。写的代码多了，看的代码也多了，由衷的觉得，写出别人看不懂的代码并不是什么能力，写出所有人都能读懂的代码，才是真的牛X。众所周知， ...

missonce 2019-08-23 17:04 评论0 收藏0
你不知道的前端SDK开发技巧

摘要：一个带提示的最后对于开发同学来说，就算不使用，也强烈建议使用提供注解，它会通过一些类型推导来检查你的代码的正确性，可以减少很多开发过程中的。相对于对象，它保证了输入的类型你定义的对象可能某一天不再只有类型的，不再需要额外的类型判断。作者：陈达孚香港中文大学研究生,《移动Web前端高效开发实战》作者之一，《前端开发者指南2017》译者之一，在中国前端开发者大会,中生代技术大会等技术...

jokester 2019-08-21 17:56 评论0 收藏0
为你的 JavaScript 项目添加智能提示和类型检查

摘要：前言最近在做项目代码重构，其中有一个要求是为代码添加智能提示和类型检查。调研了一段时间后，下文以编辑器作为开发工具，介绍一下如何为加上智能提示以及类型检查。本文首发于我的博客（点此查看），欢迎关注。前言最近在做项目代码重构，其中有一个要求是为代码添加智能提示和类型检查。智能提示，英文为 IntelliSense，能为开发者提供代码智能补全、悬浮提示、跳转定义等功能，帮助其正确并且...

zhaochunqi 2019-08-23 15:43 评论0 收藏0
vscode常用插件【全了】

摘要：插件集待补充。。。同时，它还包含了用于转换为格式和生成数据模式的选项用于压缩合并和文件的应用程序。它提供了大量自定义的设置，以及自动压缩保存并导出为文件的选项。修改文本的更多命名格式，包括驼峰命名下划线分隔命名，命名以及命名等切换漂亮的主题插件集待补充。。。 20180903 文件【Path Intellisense】自动补全路径浏览器【Open-In-Browser】在...

kyanag 2019-08-30 13:57 评论0 收藏0