摘要：的出現(xiàn)大有統(tǒng)一輕量級(jí)領(lǐng)域之勢(shì)，在其新版本中自帶了的解析功能，幫助開發(fā)者通過書寫注釋的形式向提供必要信息，完善提示功能。如果因?yàn)檫@種需求就額外的，就會(huì)破壞了代碼正常的依賴關(guān)系。

弱類型腳本語言的代碼提示功能一直是開發(fā)者一個(gè)隱隱的痛點(diǎn)，沒有它也不是不能干活，但是經(jīng)常因?yàn)槌霈F(xiàn)拼寫錯(cuò)誤或不經(jīng)意的修改導(dǎo)致的變量丟失而耗費(fèi)無畏的時(shí)間在與業(yè)務(wù)邏輯無關(guān)的地方。VSCode的出現(xiàn)大有統(tǒng)一輕量級(jí)IDE領(lǐng)域之勢(shì)，在其新版本中自帶了JSDoc的解析功能，幫助JavaScript開發(fā)者通過書寫注釋的形式向IDE提供必要信息，完善提示功能。

先來看一個(gè)簡(jiǎn)單的例子（微信小程序前端代碼）

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

可以看出該函數(shù)的定義中有一個(gè)object類型的參數(shù)o和一個(gè)函數(shù)型的回調(diào)參數(shù)callback。但是單純從代碼定義中IDE無法得知對(duì)象o中必須包含那些字段、callback回調(diào)函數(shù)中會(huì)帶回哪些參數(shù)。對(duì)于JavaScript等弱類型腳本語言來說不到運(yùn)行時(shí)階段這些信息是沒有意義的，而對(duì)于開發(fā)者而言，這些信息在一段時(shí)間以后很容易遺忘，更別說交付給第三方使用。所以這些信息就需要用JSDoc來書寫出來。

export class CommonUtilsWX {
    /**
     * 發(fā)送網(wǎng)絡(luò)請(qǐng)求，通信協(xié)議必須是http或https，數(shù)據(jù)協(xié)議必須是json
     * @param {object} o 請(qǐng)求參數(shù)對(duì)象
     * @param {string} o.host 請(qǐng)求url的域名，如http://xxx.xxx.com
     * @param {string} o.path 請(qǐng)求url的路徑，如xxx/xxx
     * @param {object} o.query 請(qǐng)求url的查詢段，根據(jù)對(duì)象中key，value拼成key1=value1&key2=value2的形式
     * @param {string} o.method 請(qǐng)求方法，如GET，POST等
     * @param {object} o.body 請(qǐng)求數(shù)據(jù)體，僅在method為POST時(shí)有效
     * @param {function(Error):void} callback 請(qǐng)求回調(diào)，請(qǐng)求成功時(shí)error為空
     */
    request(o, callback){
        //TODO:xxxxx
    }
}

可以看出JSDoc將參數(shù)o的類型和其必要的內(nèi)部構(gòu)造，函數(shù)類型的參數(shù)callback將會(huì)帶回的參數(shù)類型Error和返回值類型void，等信息都被清晰明確的標(biāo)記出來，同時(shí)附帶了文字注釋。

此時(shí)，直接使用new CommonUtilsWX()構(gòu)造出來的對(duì)象調(diào)用request()方法可以看到如下的提示畫面

然后再向request()函數(shù)傳入字面量對(duì)象時(shí)，會(huì)看到如下的提示畫面

下面是第二個(gè)例子，定義一個(gè)對(duì)象，并給對(duì)象中的字段賦予JSDoc類型信息

let zy = {
    /**
     * sdk版本號(hào)
     * @type {number}
     */
    version : 0.1,

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

    /**
     * 通用工具集，如網(wǎng)絡(luò)請(qǐng)求，彈框顯示等
     * @type {CommonUtils}
     */
    commonUtils : CommonUtils.createAdapter(),

    /**
     * 平臺(tái)功能管理，如登錄，用戶信息等
     * @type {Platform|PlatformWX}
     */
    platform : Platform.createAdapter(),

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

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

這里面除了用到@type關(guān)鍵字之外，還用到在{}中“|”符號(hào)的用法。這樣的用法代表所標(biāo)記的字段可能是多種類型的，尤其適用于我這段代碼中的情況，即一個(gè)工廠方法可能會(huì)返回屬于某個(gè)父類的任何子類對(duì)象，此時(shí)如果僅使用父類類型標(biāo)記這個(gè)字段，則在使用時(shí)IDE無法提示出子類中的特殊方法，所以用了多種可能的類型標(biāo)記后，IDE將會(huì)把所有可能類型中的提示信息都提示出來。此時(shí)的提示信息如下圖

還有另外一種方法定義一個(gè)對(duì)象中每一個(gè)字段的類型和注釋，而且可以復(fù)用，看上去更為專業(yè)，那就是@typedef關(guān)鍵字，下面就是用@typedef關(guān)鍵字重新書寫的zy對(duì)象的JSDoc：

/**
 * @typedef {object} ZY
 * @property {number} version sdk版本號(hào)
 * @property {Share|ShareWX} share 分享功能管理
 * @property {CommonUtils} commonUtils 通用工具集，如網(wǎng)絡(luò)請(qǐng)求，彈框顯示等
 * @property {Platform|PlatformWX} platform 平臺(tái)功能管理，如登錄，用戶信息等
 * @property {Leaderboard} leaderboard 排行榜功能管理
 * @property {Ad} ad 廣告功能管理
 */

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

上半部分是用@typedef關(guān)鍵字定義了一個(gè)全新的類型ZY，并且把類型中的每個(gè)字段都預(yù)先定義好。然后下半部分zy對(duì)象上方用JSDoc聲這個(gè)對(duì)象的類型是ZY。這種用法適合用在可以復(fù)用的類型對(duì)象上，或者其內(nèi)部字段沒有全部出現(xiàn)在字面上，或者沒有集中出現(xiàn)在一塊區(qū)域時(shí)。

下面又出現(xiàn)了另一個(gè)問題，VSCode是根據(jù)文件模塊的依賴關(guān)系來導(dǎo)入其他文件中的JSDoc的，比如A.js中require("B.js")，則B.js中的JSDoc信息就可以在A.js的JSDoc中使用，也能在A.js的代碼提示中顯示。但偶爾會(huì)遇到一些情況，從邏輯上A.js中并不需要
require("B.js")，而在編碼中卻需要使用B.js文件中的JSDoc。如果因?yàn)檫@種需求就額外的require("B.js")，就會(huì)破壞了代碼正常的依賴關(guān)系。于是就出現(xiàn)了如下這種用法：

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

這種方法相當(dāng)于用JSDoc的方式引入的B.js文件，并將B.js中的模塊定義為類型B。

最后奉上VSCode官方關(guān)于對(duì)JSDoc提示功能的支持文檔地址
https://github.com/Microsoft/...
https://code.visualstudio.com...

JSDoc原本是一個(gè)為JavaScript生成文檔的工具，其語法遠(yuǎn)比VSCode目前支持提示功能所用到的語法要多，有興趣可以了解一下原生的JSDoc
http://www.css88.com/doc/jsdoc/

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