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-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 the jsdoc2md.json file in your project root (right next to package.json), and add the following. You can name 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 beforementioned 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;
};