ネオキャリアグループ開発者ブログ

ネオキャリアグループの技術者による開発ブログ

ES6対応! JSのドキュメント生成ツール 【ESDoc】~ 導入編 ~

こんにちはエンジニアの松崎です。
ある日、JavaScriptのコメントルールを調査している際に見つけた
便利なツールをご紹介します!

f:id:daiki-matsuzaki:20170331114830p:plain

ESDocとは

JS(ES6)向けのAPIドキュメントツールです。
JSのドキュメントツールと言えば
JavaDocのJavaScript版JSDocというツールが多く使われています、
JavaDocとは、JavaのソースコードからHTML形式のAPI仕様書を生成できるツールです。

ESDocを導入するメリット

  • ES6 ( ECMAScript 2015 ) に対応している
  • 見やすいドキュメントを自動で生成できる
  • タグ書き方はJSDocのタグと同じ

ES6 ( ECMAScript 2015 ) に対応している

現在、ES6( ECMAScript 2015 )というJavaScriptの仕様が多く使われていますが
例えば、JSDocでコメントを書こうと思えば、
ES6 -> ES5 にトランスパイル(ソースからソースへのコンパイル)した後、ES5のコードにコメントを記述する必要があります。
ESDocではES6のコードに直接書くことができるため、全ブラウザがES6に対応し移行しても書き直す必要がありません。

見やすいドキュメントを自動で生成できる

特徴的な機能だけでも、以下の機能が提供されています。

  • マニュアルの統合
  • カバレッジ
  • Lint
  • 静的解析
  • テストコードの統合
  • 組み込み検索

この機能の詳細については次回の使用編で説明します。

タグ書き方はJSDocのタグと同じ

ESDocのタグの書き方は

/**
 * this is MyClass.
 */
export default class MyClass {
  /**
   * @param {number} a - this is a value.
   * @param {number} b - this is a value.
   * @return {number} result of the sum value.
   */
  sum(a, b){
    return a + b;
  }
}

このような形でJSDocと全く同じです。
※ESDocはJSDocのすべてのタグをサポートしているわけではないそうです。

今回実際に行った導入

早速ですがESDocを導入していきます。
導入に当たってnodeやnpm等の環境を整えるところから始めます。
(すでにnpmのインストールが済んでいる方は飛ばしてみてください)

ndenvのインストール

まずは ndenv (node.js のバージョン管理ツール)を導入します。

$ git clone https://github.com/riywo/ndenv ~/.ndenv
$ echo 'export PATH="$HOME/.ndenv/bin:$PATH"' >> ~/.bash_profile
$ echo 'eval "$(ndenv init -)"' >> ~/.bash_profile
$ exec $SHELL -l

以上を実行したら、次に今回使いたいnodeのインストールを行います。

node,npmのインストール

$ ndenv install --list

使用したいnodeのバージョンを見つけてください。
見つかれば以下を実行します。

$ ndenv install v7.7.2  # 導入したいバージョンを指定します。
$ ndenv rehash

確認を行います。

$ ndenv versions # 今までにインストールしたnodeのバージョンを表示します。
 v7.7.2

以上が表示さればインストール完了です。
実際に使用するにはグローバルとローカルでnodeを切り替えて使用します。

グローバルの場合

$ ndenv global v7.7.2 

ローカルの場合

$ ndenv local v7.7.2   #今回はこちら

localでは.node-versionというファイルが生成されます。
コマンドを打ち込んだディレクトリに移動するだけでバージョンが切り替わります。
プロジェクトごとに別バージョンのnode.jsを使用する場合はlocalで使用します。
(今回はlocalを使用しています!) 再度バージョンを表示します!

$ ndenv versions 
* v7.7.2

現在使用しているバージョンにアスタリスクがつきます。

最後にバージョンを確認します!

$ node -v
 v7.7.2
$ npm -v
 4.1.2

確認ができればnodeとnpmのインストールは完了です。

ここでnpmと言うツールが導入されましたが
npm とは Node Package Manager の略で
Node.js 用に作られたパッケージモジュールを一括で管理できるツールです。
npmで出来ること

  • JavaScript(Node.js)のパッケージやモジュールのインストール、アップデート、共有
  • npmレジストリに登録された様々な外部ライブラリやパッケージのインストール

package.jsonの作成

package.jsonとはパッケージの依存関係を記したJSONファイルです。
package.jsonで出来ること

  • ファイルにプロジェクト毎に必要なパッケージの名前とバージョンを記述すれば、npmが勝手に必要な(依存しているという)パッケージをインストールされます。
  • インストールしたパッケージが依存しているパッケージや、さらにそれが依存しているパッケージも自動でインストールされます。
  • チームで開発している場合にも、Git上に上げて共通の環境の作成や復元が簡単になります。

今回はpackage.jsonでパッケージを管理します。 まずはプロジェクトフォルダのルートで

$ npm init

と入力してください。
これでpackage.jsonファイルが生成されます。
途中対話式で設定ファイルを設定できますが
設定しない場合は、基本的にすべてEnterでいいと思います。

ESDocの導入

ここからESDocの導入になります。
先ほどインストールしたnpmでESDocをインストールします。
package.jsonの置いているディレクトリで入力します。

$ npm install -D esdoc
$ npm install

ESDocは開発で使用するため
-D オプションでpackage.jsonの devDependencies に記録します。
依存関係のパッケージもインストールするため npm install も行います。

.esdoc.jsonファイル

esdocの設定ファイルになります。
以下のコマンドを入力してください

$ echo '{"source": "./src", "destination": "./doc"}' > .esdoc.json

このコマンドで.esdoc.jsonファイルを生成し設定を記録しています。

  • "source" ではesdocで対象になるディレクトリを指定します。
  • "destination" では生成されるhtmlファイルを書き出すディレクトリを指定します。

次にpackage.json内にscriptを記述します。

{
  "scripts": {
    "esdoc": "esdoc; open esdoc/index.html"
  },
  "devDependencies": {    # ここは先ほど生成された箇所です。
    "esdoc": "^0.5.2"
  }
}

次に

$ npm run esdoc

を実行します。 これで先ほど設定したesdocが実行され、さらに生成されたhtmlをブラウザで開くことができます。

今回は導入までを行いました。 次回はESDocの使い方について書いていこうと思います!

参考サイト

esdoc.org

github.com

弊社について

ネオキャリアでは、エンジニアの募集を行っています。
ぜひ!募集記事をチェックしていただけると嬉しいです!(*>ω<)b

www.wantedly.com

www.wantedly.com