从JavaScript生成TypeScript定义时如何保留枚举成员的文档？

TypeScript在从JS文件生成.d.ts时，对JSDoc @enum的成员注释支持存在局限，不过可以通过两种方式解决：

方法一：改用TypeScript原生枚举（推荐） #

如果能把JS文件转为TS文件，直接用TS原生枚举并给每个成员加JSDoc注释，生成的.d.ts会完整保留所有注释：

/**
 * 表示方向的枚举类型
 */
enum Direction {
    /**
     * 向上方向
     */
    Up = 1,
    /**
     * 向下方向
     */
    Down = 2,
    /**
     * 向左方向
     */
    Left = 3,
    /**
     * 向右方向
     */
    Right = 4
}

方法二：调整JS文件的JSDoc注释格式 #

如果必须保持JS文件格式，要放弃@enum的简化写法，改用@typedef搭配@type的完整语法，把成员注释写在@property的描述里：

/**
 * @typedef {Object} Direction
 * @property {number} Up - 向上方向
 * @property {number} Down - 向下方向
 * @property {number} Left - 向左方向
 * @property {number} Right - 向右方向
 */
/** @type {Direction} */
const Direction = {
    Up: 1,
    Down: 2,
    Left: 3,
    Right: 4
};

module.exports = Direction;

同时确保tsconfig.json里的关键配置：

{
  "compilerOptions": {
    "declaration": true,
    "removeComments": false,
    "allowJs": true
  }
}

这样生成的.d.ts会完整保留枚举和所有成员的注释。

内容的提问来源于stack exchange，提问作者Sam Fischer