ESDoc v1.0をリリースするために、機能をプラグイン化してコアと周辺機能を分離しています。 https://github.com/esdoc/esdoc-plugins

この作業は大体終わり、現在はよりadvancedなプラグインのPoCを作成しています。そこで、今回はFlowとTypeScriptをESDocで扱うための2つのプラグインを紹介します。

ESDoc v1.0自体ついては正式リリース後に紹介する予定です。

FlowをESDocで使用する

Flowで書かれたコードをESDocで使用可能にするプラグインです。

このプラグインはPoCなので、実現可能性を確かめるためだけの最小実装となっています。

このプラグインを使用するにはESDoc@alphaが必要です。

npm i esdoc@alpha esdoc-standard-plugin esdoc-flow-type-plugin

必要な設定を.esdoc.jsonに記述します。

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

esdocを実行してドキュメントを作成します。

esdoc
open doc/index.html

TypeScriptをESDocで使用する

TypeScriptで書かれたコードをESDocで使用可能にするプラグインです。

このプラグインはPoCなので、実現可能性を確かめるためだけの最小実装となっています。

このプラグインを使用するにはESDoc@alphaが必要です。

npm i esdoc@alpha esdoc-standard-plugin esdoc-typescript-plugin

必要な設定を.esdoc.jsonに記述します。

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

esdocを実行してドキュメントを作成します。

esdoc
open doc/index.html

基本戦略は「Flowの型情報をドキュメントコメントに埋め込む」というものです。これができれば後はESDocの処理フローに任せることができます。

Flowはbabylon(babelで使われているECMAScriptパーサ)でパースし、ASTに含めることが可能です。なので、以下のように型情報をドキュメントコメントに埋め込みました。

babylonのflowプラグインを有効にしてFlowコードをパースしてASTにする
ASTをトラバースし、対象(メソッドや関数)のnodeに対して
- nodeから型情報を取得
- 「既存のドキュメントコメント」と「型情報」から「新しいドキュメントコメント」を生成
- nodeのコメントを置き換える

基本戦略はFlowと同じで「TypeScriptの型情報をドキュメントコメントに埋め込む」というものです。後はTSをESに変換し、ESDocの処理フローに任せることができます。

TypeScriptはbabylonではパースすることができません。 ※babylonにTSのプラグインを導入するPRは出されているようです

そこでTypeScriptコンパイラを使用して、以下のように型情報をドキュメントコメントに埋め込みました。

TSコンパイラでコードをパースしてASTにする
ASTをトラバースし、対象（メソッドや関数）のnodeを集める
nodeの一覧を順番にループさせて、
- nodeから型情報を取得
- 「既存のドキュメントコメント」と「型情報」から「新しいドキュメントコメント」を生成
- 元のTSコードのドキュメントコメントを置き換える(文字列操作)
ドキュメントコメントを置き換えたTSコードをESにトランスパイルする

1点泥臭いのは「ドキュメントコメントを書き換えるのに、TSコードを文字列操作する」ことです。 TS ASTを書き換えて、新たなTSコードを生成できればよかったのですが、TS ASTを書き換える方法がわかりませんでした。もし知っている方がいれば教えて頂けるとありがたいです。

これらのプラグインに興味がある方は是非試用してみてください。

僕自身はFlowもTypeScriptも使っていないのでpull requestをお待ちしております。