有没有办法将`jsdoc`与`.ts`文件一起使用？也许用 babel 转译然后使用 jsdoc？

Question

有没有办法将 jsdoc 与 typescript 文件一起使用？ 我尝试使用

jsdoc-babel

与此配置

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

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

那么你们到底使用 jsdoc 和 typescript 吗？

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 编写了一个使用 TypeScript 和 jsdoc2md 的 wiki 页面。

可能有帮助：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

Answer 2

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

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

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

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

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

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

Answer 3

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

Answer 4

我遇到了同样的问题，我通过使用 better-docs 插件解决了它https://github.com/SoftwareBrothers/better-docs