How to document TypeScript

Babel started to support TypeScript from version 7.

Since most modules are at pre-release stage as of this writing, I had to insert latest version numbers by hand. Update version numbers accordingly. After pre release stage, there would be no need to put version numbers.

1. Install Related Modules

Either run the following:

npm install -save-dev typescript [email protected] @babel/[email protected] @babel/[email protected] @babel/[email protected] @babel/[email protected] @babel/[email protected] @babel/[email protected] [email protected] jsdoc-to-markdown

or add devDependencies entries to your package.json and run npm install:

package.json

{
  "devDependencies": {
    "@babel/cli": "^7.0.0-beta.40",
    "@babel/core": "^7.0.0-beta.40",
    "@babel/plugin-proposal-class-properties": "^7.0.0-beta.40",
    "@babel/plugin-proposal-object-rest-spread": "^7.0.0-beta.40",
    "@babel/preset-env": "^7.0.0-beta.40",
    "@babel/preset-typescript": "^7.0.0-beta.40",
    "jsdoc-babel": "^0.4.0-alpha.0",
    "jsdoc-to-markdown": "^4.x"
  }
}

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.

jsdoc2md.json

{
  "source": {
    "includePattern": ".+\\.(j|t)s(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": "current" } }], "@babel/typescript"],
    "plugins": ["@babel/proposal-class-properties", "@babel/proposal-object-rest-spread"]
  }
}

This configuration:

• Excludes your-file.test.ts and your-file.spec.ts files from compilation and documentation.
• Using @babel/preset-env, targets current node version for conversion. (You can change and test it according to your needs)

3. Setup Build Task

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

Also see Redundant Entries below.

package.json

{
  "scripts": {
    "build:doc": "jsdoc2md --files 'src/**/*.ts' --configure jsdoc2md.json > README.md"
  }
}

Tips & Tricks

Redundant Entries

I don't know the reason, but sometimes, every items are added to the documentation twice. In that case clearing cache using --no-cache option solves my problem.

"jsdoc2md --no-cache --files 'src/**/*.ts' --configure jsdoc2md.json > README.md"

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

Not so elegant, but I add a stub code below removed comments. For example

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

Using Template and Adding Table of Contents

As a preference, I use a template and add table of contents to my README.md. Below are necessary configuration and files:

Install doctoc

npm install -save-dev doctoc

package.json

{
  "scripts": {
    "build:doc": "jsdoc2md --files 'src/**/*.ts' --configure jsdoc2md.json --template README.hbs > README.md && doctoc README.md"
  }
}

README.hbs

<!-- DO NOT EDIT README.md (It will be overridden by README.hbs) -->

# name

One line description.

<!-- START doctoc -->
<!-- END doctoc -->

# Description

More detailed description

# Synopsis

Code samples

# API
{{>main~}}