【问题标题】：Is there any way to use `jsdoc` with `.ts` files? Maybe transpile with babel then use jsdoc?有没有办法将 `jsdoc` 与 `.ts` 文件一起使用？也许用 babel 转译然后使用 jsdoc？
【发布时间】：2019-11-06 06:31:11
【问题描述】：

是否可以将 jsdoc 与 typescript 文件一起使用？我尝试在此配置中使用jsdoc-babel

{
  "plugins": [
    "node_modules/jsdoc-babel"
  ],
  "babel": {
    "extensions": [
      "js",
      "es6",
      "jsx",
      "ts",
      "tsx"
    ]
  }
}

但是不行，或许我们可以手动转译ts文件，然后生成jsdocs？我知道 typedoc 之类的替代方案，但它缺少许多重要功能。

那么你们无论如何都使用带有 typescript 的 jsdoc 吗？

【问题讨论】：

标签： typescript jsdoc

【解决方案1】：

尽管@Remi TypeDoc 表示更适合 TypeScript，但我使用 JSDoc 来更好地进行 jsdoc 到 markdown 的转换（在撰写本文时）。

方法一：

编译 TypeScript 并将 JSDoc 与编译后的代码一起使用

> tsc && nodemon node_modules/.bin/jsdoc -c jsdoc.json dist/**/*

方法二：

我正在使用下面的方法和 jsdoc2markdown（它使用 jsdoc）。使用jsdoc-babel、@babel/cli、@babel/core、@babel/preset-env、@babel/preset-typescript 和以下 jsdoc 配置：

{
  "source": {
    "includePattern": ".+\\.ts(doc|x)?$",
    "excludePattern": ".+\\.(test|spec).ts"
  },
  "plugins": [
    "plugins/markdown",
    "node_modules/jsdoc-babel"
  ],
  "babel": {
    "extensions": ["ts", "tsx"],
    "ignore": ["**/*.(test|spec).ts"],
    "babelrc": false,
    "presets": [["@babel/preset-env", { "targets": { "node": true } }], "@babel/preset-typescript"],
    "plugins": ["@babel/proposal-class-properties", "@babel/proposal-object-rest-spread"]
  }
}

这个配置：

从编译和文档中排除 your-file.test.ts、your-file.spec.ts 和 your-file.js 文件。
包括 your-file.ts、your-file.tsdoc 和 your-file.tsx
使用@babel/preset-env，以当前节点版本为目标进行转换。（您可以根据需要更改和测试它）=> 参见 preset-env 文档
使用 @babel/preset-typescript 使 babel 能够解析 TypeScript

提示和技巧

JSDoc 注释消失

Babel 和 TypeScript 在编译过程中删除了一些 JSDoc cmets：

通天塔/通天塔#6898：transform-flow-strip-types removes all jsdoc comments
通天塔/通天塔#5512：Babel very strange move comments

通过添加如下所示的 STUB 代码可以解决此问题：

let STUB = 1;

/**
 * Some description
 * @typedef {Object} Config
 * @property {string}  name  - Name of the config.
 * @property {string}  color - Color of choice.
 */
STUB = 1;

export type Config = {
  name: string;
  color: string;
};

~~我很久以前使用 jsdoc-babel 编写了一个 wiki 页面，用于将 TypeScript 与 jsdoc2md 结合使用。~~

可能有帮助：https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/How-to-document-TypeScript

方法 3（TypeDoc）

这不是直接询问的内容，而是与之密切相关。以下工作流程可能有用：

使用 TypeDoc 生成 HTML 页面。
使用typedoc-plugin-markdown 生成多个 MarkDown 页面。
使用concat-md 从多个 MarkDown 页面生成单个 MarkDown 页面。（这是我最近开发的一个 npm 包，用于解决我的 JSDoc/TypeScript 单页 MarkDown 需求。）

示例

$ typedoc --plugin typedoc-plugin-markdown --mode file --out docs
$ npx concat-md --decrease-title-levels --dir-name-as-title docs > README.md

【讨论】：

【解决方案2】：

虽然使用JSDoc结合Typescript有一定的好处，比如：

结构直接从源头收集
TypeScript 的注解更加紧凑

缺点是采用 TypeScript 需要大量工作才能使构建工具适应您当前的流程（正如您目前所经历的那样）

相反，您可以使用类似http://typedoc.org/

它将持续关注您的文档更改，并将根据代码库更改重新构建。

来源：https://blog.cloudflare.com/generating-documentation-for-typescript-projects/#whynotjsdoc

【讨论】：

【解决方案3】：

试用用于 typescript 的 JSDoc 插件，它是 Better-docs 工具集的一部分：https://github.com/SoftwareBrothers/better-docs。

【讨论】：