How to document TypeScript

Babel started to support TypeScript from version 7.

1. Install Required Modules

Run the following:

npm install -save-dev typescript jsdoc-babel @babel/cli @babel/core @babel/preset-env @babel/preset-typescript jsdoc-babel jsdoc-to-markdown

# substitute "npm install --save-dev" with "yarn add -D" when using yarn

Furthermore

• If you use Class Properties (Class SomethingOrOther) you'll have to add: npm install --save-dev @babel/plugin-proposal-class-properties
• If you use Object Rest/Spread (let { x, y, ...z } = { x: 1, y: 2, a: 3, b: 4 };) you'll have to add npm install --save-dev @babel/plugin-proposal-object-rest-spread

2. Create jsdoc Configuration in Project Root

Create jsdoc2md.json file in project root, and add the following. You can the file as you wish. In case you choose a different name, change it in package.json scripts too. If you did not install either of the aforementioned plugin-proposals please exclude either or both of them from the plugins property!

jsdoc2md.json

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

3. Setup Build Task

Add the following to the "scripts" section of your package.json

Please note:

• In case some or every item gets added multiple times add --no-cache to the script
• Substitute ./path/to/typescript/files/*.ts with a proper path to the TypeScript files you want to document, for example ./src/*.ts
• Substitute ./path/to/output/file.md with the proper path where you want to output the result, for example ./docs/index.md
• If you use a handlebars template include it with --template ./path/to/template.hbs, for example ./docs/template.hbs

package.json

{
  "scripts": {
    "build:doc": "jsdoc2md --files ./path/to/typescript/files/*.ts --configure ./jsdoc2md.json > ./path/to/output/file.md"
  }
}

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