在 TypeScript 中使用 JSDoc 為函數的多個對象參數寫注釋

最近在將一個使用 JavaScript 寫的 npm 包重構成 TypeScript 。重構完后，發現原先的 JSDoc 注釋在 ts 文件編譯后失效了，便搜索了一下，但是谷歌並沒有找到我所想要的答案，便只能自己研究了。這篇算是記錄一下研究結果。

首先說明一下 JSDoc 的函數參數注釋寫法：在函數上方，內容放置於多行注釋內，下面是一個基礎的例子，詳細內容請參考 Use JSDoc: @param

/**
 * @param somebody
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}

至於為什么要使用 JSDoc ？因為可以為函數參數添加描述信息（這樣更新參數后就不用更新文檔啦 x ）。

我先試着使用了 TypeScript 的 interface 關鍵詞，先編寫兩個接口，然后將函數的參數的類型設置成對應接口，但是這樣會使 VSCode 的代碼提示只顯示函數參數的類型，不顯示類型的內容（如圖 1 所示），具體例子如下

/** 這是 bar 數組 */
interface Bar {
  /** 這是 bar 數組的 i 字段 */
  i: string;
  /** 這是 bar 數組的 j 字段 */
  j: string;
}
/** etc 對象 */
interface Etc {
  /** 這是 etc 對象的 x 字段 */
  x: boolean;
  /** 這是 etc 對象的 y 字段 */
  y: string;
  /** 這是 etc 對象的 z 字段 */
  z: string;
}
/** foo 函數的描述
 * @param {Bar[]} bar - 這是 bar 數組
 * @param {String} bar[].i - 這是 bar 數組的 i 字段
 * @param {String} bar[].j - 這是 bar 數組的 j 字段
 * @param {Etc} etc - etc 對象
 * @param {Boolean} etc.x - 這是 etc 對象的 x 字段
 * @param {String} etc.y - 這是 etc 對象的 y 字段
 * @param {String} etc.z - 這是 etc 對象的 z 字段
 */
const foo = (
  bar: Bar[] = [],
  etc: Etc = {
    x: true,
    y: './y',
    z: '',
  },
) => {};

  

 圖 1

這顯然不是我所想要的。於是便嘗試不將類型抽離，而是直接在函數參數后面定義，寫完編譯后看結果，完美。例子如下

/** foo 函數的描述
 * @param {Object[]} bar - 這是 bar 數組
 * @param {Object} etc - etc 對象
 */
const foo = (
  bar: {
    /** 這是 bar 數組的 i 字段 */
    i: string;
    /** 這是 bar 數組的 j 字段 */
    j: string;
  }[] = [],
  etc: {
    /** 這是 etc 對象的 x 字段 */
    x: boolean;
    /** 這是 etc 對象的 y 字段 */
    y: string;
    /** 這是 etc 對象的 z 字段 */
    z: string;
  } = {
    x: true,
    y: './apis',
    z: '',
  },
) => {};

 圖 2