Is there any way to use `jsdoc` with `.ts` files? Maybe transpile with babel then use jsdoc?

Question

Is there anyway to use jsdoc with typescript file? I tried using jsdoc-babel with this config

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

But it doesn't work, maybe we can transpile ts files manually and then generate jsdocs? I know of alternatives like typedoc but it lacks many important features.

So do you guys use jsdoc with typescript anyhow?

Solution 1

Although as stated by @Remi TypeDoc is a better fit for TypeScript, I use JSDoc for better jsdoc to markdown conversion (as of this writing).

Method 1:

Compile TypeScript and use JSDoc with compiled code

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

Method 2:

I'm using below method with jsdoc2markdown (which uses jsdoc). Using jsdoc-babel, @babel/cli, @babel/core, @babel/preset-env, @babel/preset-typescript with below jsdoc configuration:

{
  "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"]
  }
}

This configuration:

• Excludes your-file.test.ts, your-file.spec.ts and your-file.js files from compilation and documentation.
• Includes your-file.ts, your-file.tsdoc and your-file.tsx
• Using @babel/preset-env, targets current node version for conversion. (You can change and test it according to your needs) => See the preset-env documentation
• Using @babel/preset-typescript gives babel the capability to parse TypeScript

Tips & Tricks

JSDoc Comments Disappear

Babel and TypeScript removes some JSDoc comments during transpilation:

• babel/babel#6898: transform-flow-strip-types removes all jsdoc comments
• babel/babel#5512: Babel very strange move comments

There is a hacky fix for this by adding a STUB code as seen below:

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;
};

I wrote a wiki page for using TypeScript with jsdoc2md using jsdoc-babel long ago.

It may help: https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/How-to-document-TypeScript

 Method 3 (TypeDoc)

This is not directly what is asked, but strongly related to it. Below workflow may be useful:

• Using TypeDoc to generate HTML pages.
• Using typedoc-plugin-markdown to generate multiple MarkDown pages.
• Using concat-md to generate single MarkDown page from multiple MarkDown pages. (This is an npm package developed by me lately to solve my JSDoc/TypeScript single page MarkDown requirement.)

Example

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

Solution 2

Although using JSDoc in combination with Typescript has certain benefits, such as:

• the structure is gleaned directly from the source
• annotations for TypeScript are much more compact

The downside is that adopting TypeScript requires a large amount of work required to fit the build tools into your current processes (as you currently are experiencing)

Instead, you can use something like http://typedoc.org/

It will continuously keep your documentation changes on watch and will re-build on codebase changes.

Source: https://blog.cloudflare.com/generating-documentation-for-typescript-projects/#whynotjsdoc

Solution 3

Try out the JSDoc plugin for typescript, which is a part of better-docs toolset: https://github.com/SoftwareBrothers/better-docs.