「ビットコイン自動売買用ccxt拡張」 ESDocを導入しました

目次
・ESDocの導入
・APIリファレンスを作ってみよう
・ESDoc とは

●ESDocの導入

先日公開しました「ビットコイン自動売買用ccxt拡張」のプロジェクトにESDocを導入しました。

すでに購入済みの方は gitlabよりプロジェクトをPullしてくだされば ESDocを使用できるようになります。

今回はpackage.json に変更を加え、ファイルを１つ追加しただけなので、ご自身のローカルpackage.jsonファイルを以下のようにしていただければ同じ効果が得られます。

{
  "name": "ex-ccxt",
  "version": "0.0.2",
  "description": "bitcoin trading module - extension ccxt (use ccxt module)",
  "main": "server.js",
  "scripts": {
    "start": "node -r babel-register src/server.js",
    "build": "babel src -d dist --source-maps",
    "esdoc": "esdoc; open ./docs/index.html"
  },
  "author": "o-matsuo",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://gitlab.com/bitcoin-bot/ex-ccxt.git"
  },
  "devDependencies": {
    "babel-cli": "^6.26.0",
    "babel-plugin-transform-runtime": "^6.23.0",
    "babel-preset-env": "^1.6.1",
    "babel-register": "^6.26.0",
    "esdoc": "^1.1.0",
    "esdoc-standard-plugin": "^1.0.0"
  },
  "dependencies": {
    "bluebird": "^3.5.1",
    "ccxt": "^1.14.172",
    "node-fetch": "^2.1.2",
    "rxjs": "^6.2.0",
    "rxjs-compat": "^6.2.0"
  }
}

追加したモジュールは以下の２点です。

・esdoc
・esdoc-standard-plugin

以前からJSDocは知っていましたが、ES6(ECMA2015)対応版のJSDocがVer.1になっているとは気がつきませんでした。

JSDocはES6の記述には対応していないので、利用するとしたら

ES6形式で記述　→　babelでトランスパイラ　→　ES5形式　→　JSDoc

という流れになってしまい、ES6で書く魅力が半減してしまうので、JSDocの導入に二の足を踏んでいました。

ESDocはES6形式の記述をそのままドキュメント化できるので Ver.1のリリースを待っていましたが、実はもう去年にリリースされていたようです。（完全にウオッチ不足でした）

●APIリファレンスを作ってみよう

package.json ファイルを先ほどのように修正し、コマンドラインから

npm install

を実行してモジュールをインストールしましょう。

プロジェクトのルートに「.esdoc.json」というファイルを作ります。

内容を以下のようにします。

{
    "source": "./src",
    "destination": "./docs",
    "plugins": [{"name": "esdoc-standard-plugin"}]
}

ファイルを作成したら、以下のコマンドを実行します。

npm run esdoc

すると、「docs」というフォルダが作成され、次にブラウザでesdocが表示されるはずです。

このように表示されたら、左ペインから「cBase」をクリックしてみましょう。

このようなリファレンスが表示されます。

現状はソースコードの方をJSDoc形式でちゃんと記述できていないので、ほとんど説明が反映されていませんが、APIの引数等は以下のように確認することができます。

今後、cBase, cBitMEXクラスの機能拡張とともに説明文も随時追加していきますので、よろしくお願いいたします。

●ESDoc とは

ES6(ECMA2015)以降のJavaScriptを対象としたドキュメンテーションツールです。

APIドキュメントって、作っても作ってもすぐに陳腐化してしまうので、開発者泣かせな一面があります。

このESdocは「コードからAPIドキュメントを作って」くれます。

ESDocという(多分)モダンなドキュメンテーションツールの紹介 - maru source

DocツールといえばJavaDocが有名ですね。

そのES版というところでしょうか。

esdoc-site

esdoc/esdoc

クラスが太っていくとAPIの内容を逐一確認するのも困難になります。

ESDocで素早く対象のAPIを見つけられると助かります。

ESDocはドキュメンテーションの他に、いろいろな機能があるので、利用できたタイミングでアナウンスしていきますので、宜しくお願い致します。

ご期待いただければ「スキ」ボタンをポチっと、「フォロー」ボタンをクリック、よろしくお願いいたします。

note: https://note.mu/o_matsuo

twitter: @o_matsuo
もフォローしてくださると、喜びます。

あ、それから私の師匠である
コンドウ様のnoteもポチっとしていただけると、さらに喜びます。