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

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

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


こんにちはエンジニアの松崎です。
前回導入までを行なったESDocの続きです。

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

今回は主にESDocの特徴的な機能である以下について紹介していきます。

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

マニュアルの統合

ESDocではJavaScriptの開発に使用する、ドキュメントを一括で管理することができます。

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

使い方

まずはMarkdownファイルを作成します。

  1. rootディレクトリ配下にmanualフォルダを作成します。
  2. 今回はusage.mdファイルを作成します。
  3. 一行目に # Usage を必ず入れてください!
  4. Markdownでドキュメントを作成してください!

次に前回ESDocの導入編で作成した .esdoc.json に設定を追記します。

{
  "source": "./src",
  "destination": "./esdoc",
  "manual": {
    "globalIndex": true,
    "usage": ["./manual/usage.md"],
  }
}


上記の "manual" が今回追記した部分になります。

設定項目の詳細は以下になります。

  • manual と言うキーの中に設定項目を記入します。
    (*以下の書き方は全て決まっているため別の名前をつけるとマニュアルに変換できません)
  • globalIndex は目次(マニュアルの項目)をESDocのHomeに表示するかの設定です。 指定した場合、HomeディレクトリのREADMEは表示されません。
  • usage は使用方法のマニュアルを使用する設定です。

そのほか

  • Overview
  • Design
  • Installation
  • Usage
  • Tutorial
  • Configuration
  • Example
  • Advanced
  • FAQ
  • Changelog

これだけのマニュアルを作成・分類することができます。

カバレッジ

コメントが書かれるべきところ(クラス等)にどれだけ書かれているのか確認する機能です。

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


このように自動的にファイルごとにカバレッジを出力してくれます。

Lint

ソースコードに対して書いたコメントの引数名と実際の引数名に違いがあった場合
esdocコマンド実行時にエラーとして出力されます。

export default class Foo {
  /**
   * @param {number} x
   */
  method(p){}
}
 warning: signature mismatch: Foo#method src/~~~~

静的解析

コメントなどが一切書かれていないソースコードでも、ソースコードからわかる情報で
最低限のドキュメントを作成してくれます。

例えば「継承されているClass」や「return文の戻り値の存在」などです。

テストコードの統合

JSで使用しているテストコードもESDocで管理することができます。

使い方

※今の所対応がmochaのみとなっているみたいです。


今回も .esdoc.jsonファイルに追記して設定します。

{
  "source": "./src",
  "destination": "./doc",
 "manual": {}
  "test": {
    "type": "mocha",
    "source": "./test"
  }
}

testの部分が今回追記した設定になります。

  • test と言うキーの中に設定項目を記入します。
  • type に今回テストで使用する "mocha" を設定します。
  • source にテストコードを配置しているディレクトリを指定します。 ※ mocha標準でtestディレクトリにテストコードを配置するため "./test" を設定しています。


以上で設定は完了しました。 後は、テスト対象のコードにコメントを追記します。

/** @test {MyClass} */
describe('MyClass is super useful class.', ()=>{

  /** @test {MyClass#sayMyName} */
  it('say my name', ()=>{
    let foo = new MyClass('Alice');
    assert.equal(foo.sayMyName(), 'My name is Alice');
  })
});


@test に続けてクラス名やメソッド名を記入することで関連付けすることができます。


このとき @test{クラス名}@test {クラス名#メソッド名} はソースコードのクラス名、メソッド名と一致させてください!


ソースコードにテストコードへのリンクが貼られました。 f:id:daiki-matsuzaki:20170501022401p:plain

これでソースコードのドキュメントからテストコードへのドキュメントへの
移動が簡単にできるようになりました!

組み込み検索

ESDoc内で管理されているClassやメソッドを検索することができます。

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

悩み...

今回、悩んだところはマニュアルを分割させるところです。

ESDocではMarkdownファイルはHTMLファイルに変換されるためリンク先はhtmlファイルにしなければいけませんでした。

# Overview
[使い方](./usage/usage.html)


さらに開いたリンクを項目の位置までジャンプさせたかったので
以下のようにMarkdownにHTMLを埋め込みました。

<h1 id ="overview"> Overview </h1>
[カバレッジ機能の使い方](./usage/usage.html#esdoc-coverage)
<h1 id="usage"> Usage </h1>
<h3 id="esdoc-coverage"> ESDocのカバレッジの使い方 </h3>


ただマニュアルの管理方法は人それぞれなので自分のやりやすい方法にしてください!

最後に

今はESDocを使用検討中なのですが、サンプルを作成した際、見た目も含めかなり見やすく
検索機能のおかげで目的のファイルまでの移動がかなり楽だと感じました。

ただ、es6のclass構文だけのサポートになっているのでJavaScriptのfunctionベースのコードや
prototypeベースのコードで使用できない点など、ESDocは全てのプロジェクトですることは導入が難しいと感じました。

参考サイト

esdoc.org

github.com

弊社について

弊社ではエンジニアの募集を行っております! ぜひ募集記事をチェックして頂けると嬉しいです!

www.wantedly.com

www.wantedly.com