VSCode + JSDoc 完美實現（almost）JavaScript代碼提示

wslongchen 發布于2019-08-23 10:23 / 1422人閱讀

摘要：的出現大有統一輕量級領域之勢，在其新版本中自帶了的解析功能，幫助開發者通過書寫注釋的形式向提供必要信息，完善提示功能。如果因為這種需求就額外的，就會破壞了代碼正常的依賴關系。

弱類型腳本語言的代碼提示功能一直是開發者一個隱隱的痛點，沒有它也不是不能干活，但是經常因為出現拼寫錯誤或不經意的修改導致的變量丟失而耗費無畏的時間在與業務邏輯無關的地方。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/

最后嗶嗶兩句，入技術圈五六年來第一次發博，也是被很多資深博主的感化，發博一方面是分享自己技術方面的心得，分享過程中獲得更多，一方面是提高自己書面表達能力。但入一個坑總得一步一步的入，所以先從可有可無的雕蟲小技開始。

云服務器 GPU云服務器 js實現提示語音 js實現輸入提示 js實現搜索輸入提示 almost

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/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