JsDocをもとにドキュメントを自動生成する

Documentation.js

コマンドひとつで、ドキュメントを自動生成してくれる！

まずは、JsDocで記述

JsDocの概要については、おググりください。
VSCodeとかだと、関数の上の行で/** + EnterでJsDocテンプレートが挿入される

import { TweenMax } from 'gsap';

/**
 * TweenMax の基本操作
 */
export default class TweenAnimation {
  /**
   * @param {any} target
   * @param {number} duration
   * @param {gsap.TweenConfig} vars
   */
  constructor(target, duration, vars) {
    this._tween = TweenMax.to(target, duration, vars);
  }

  /**
   * アニメーションを止める
   * @param {any} [atTime]
   * @param {boolean} [suppressEvents]
   */
  pause(atTime, suppressEvents) {
    this._tween.pause(atTime, suppressEvents);
  }
}

生成されたドキュメント (HTML形式の場合) の一部

使い方

インストール

yarn add -D documentation
(or npm i -D documentation)

HTML形式でドキュメント生成

documentation build path/to/your/javascript.js -f html
documentation build src/** -f html -o docs

MarkDown形式でドキュメント生成

documentation build path/to/your/javascript.js -f md
documentation build src/** -f md -o docs.md

オプションについて

• -f: フォーマット (html, md)
• -o: アウトプット(出力)
  • HTML形式の場合、生成するディレクトリ名を指定
    • index.htmlやassets/が格納される
  • MarkDown形式の場合、ファイル名.md

番外編: ファイルに変更があったら、ドキュメントを更新

• さらに、HTMLでもMarkDownでも生成したい場合の例

yarn add -D documentation chokidar-cli npm-run-all
(or npm i -D documentation chokidar-cli npm-run-all)

package.json

"scripts": {
  "watch": "chokidar 'src/es6/**' -c 'npm run docs'",
  "docs": "npm-run-all -p docs:*",
  "docs:html": "documentation build src/es6/** -f html -o docs/es6",
  "docs:md": "documentation build src/es6/** -f md -o docs/es6/README.md"
}

実行
yarn watch

参考

• Documenting Javascript Projects With JSDoc, Flow, and Documentation.js
  • https://medium.com/4thought-studios/documenting-javascript-projects-f72429da2eea