有什么方法可以将 `jsdoc` 与 `.ts` 文件一起使用吗？也许用 babel 编译然后使用 jsdoc？

Question

无论如何可以将jsdoc与打字稿文件一起使用吗？我尝试使用jsdoc-babel此配置

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

但是不行，也许我们可以手动转译ts文件，然后生成jsdocs？我知道像 typedoc 这样的替代品，但它缺乏许多重要的功能。

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

Answer 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 注释：

• babel/babel#6898：transform-flow-strip-types 删除所有 jsdoc 注释
• babel/babel#5512: Babel 非常奇怪的移动评论

通过添加如下所示的 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

 方法三（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

Answer 2

尽管将 JSDoc 与 Typescript 结合使用有一定的好处，例如：

• 该结构是直接从源头收集的
• TypeScript 的注释更加紧凑

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

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

它将持续关注您的文档更改，并将在代码库更改的基础上重新构建。

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