有什么办法可以将jsdoc和.ts文件一起使用？也许与babel进行转译，然后使用jsdoc？

Question

有没有可以将jsdoc与打字稿文件一起使用？ 我尝试在此配置中使用jsdoc-babel

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

但是它不起作用，也许我们可以手动翻译ts文件，然后生成jsdocs？ 我知道像typedoc这样的替代方法，但是它缺少许多重要功能。

那么你们是否将jsdoc与typescript一起使用？

Answer 1

尽管结合使用JSDoc和Typescript具有某些好处，例如：

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

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

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

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

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

Answer 2

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

Answer 3

尽管@Remi TypeDoc所说的类型更适合TypeScript，但我使用JSDoc来实现更好的jsdoc到markdown的转换（在撰写本文时）。

方法1：

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

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

方法2：

我正在使用jsdoc2markdown（使用jsdoc）的以下方法。在以下jsdoc配置中使用jsdoc-babel，@babel/cli，@babel/core，@babel/preset-env，@babel/preset-typescript，

{
  "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，以当前节点版本为目标进行转换。 （您可以根据需要进行更改和测试）=>请参阅预设环境文档
• 使用@babel/preset-typescript使babel能够解析TypeScript

提示和技巧

JSDoc注释消失

Babel和TypeScript会在翻译过程中删除一些JSDoc注释：

• babel / babel＃6898：transform-flow-strip-types removes all jsdoc comments
• babel / babel＃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;
};

我很早以前就写了一个Wiki页面，使用jsdoc-babel将TypeScript与jsdoc2md一起使用。

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