从TypeScript编译的JS文件使用JSDoc生成文档失败

问题场景 #

我编写了如下简单的TypeScript类代码：

export class Address
{
    /**
     * @param street { string } - omit building number
     * @param city { string } - short names like "NYC" are fine 
     */
    constructor(
        private readonly street: string,
        private readonly city: string){}
}

export class Person
{
    /**
     * @param name { string } - private name only
     * @param address { Address } - home address
     */
    constructor(
        private readonly name: string,
        private readonly address: Address){}
}

先执行TS编译命令生成JS和对应的.d.ts文件：

$ ./node_modules/.bin/tsc --declaration main.ts

接着用JSDoc生成文档时，结果页面仅显示“Home”文字，没有任何类或参数的文档内容：

$ ./node_modules/.bin/jsdoc --verbose ./main.js

问题原因 #

JSDoc默认不支持TypeScript语法，直接处理编译后的JS文件时，TS的private成员会被编译成内部变量（比如#street），JSDoc无法识别这些私有成员及对应注释；同时编译后的JS文件会丢失部分TS特有的类结构信息，导致JSDoc无法解析出完整的文档内容。

解决方法 #

直接让JSDoc处理TypeScript源文件，借助插件实现TS语法支持：

1. 安装TS支持插件

npm install jsdoc-plugin-typescript --save-dev

2. 创建JSDoc配置文件jsdoc.json，配置内容如下：

{
  "plugins": ["node_modules/jsdoc-plugin-typescript"],
  "source": {
    "include": ["main.ts"],
    "includePattern": "\\.(ts|tsx)$",
    "excludePattern": "(node_modules/|docs/)"
  },
  "opts": {
    "destination": "./docs",
    "recurse": true
  }
}

3. 执行JSDoc命令生成完整文档

$ ./node_modules/.bin/jsdoc -c jsdoc.json

执行完成后，./docs目录下会生成包含类、构造函数参数注释的完整文档。

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