FlowとTypeScriptをESDocで使用する

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

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

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

FlowをESDocで使用する

esdoc-flow-type-plugin

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

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

  • ドキュメントコメントに型情報が書かれていない場合、Flowの型アノテーションから型を取得する
  • 型推論による型情報の取得は未実装

このプラグインを使用するには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で使用する

esdoc-typescript-plugin

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

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

  • ドキュメントコメントに型情報が書かれていない場合、TypeScriptの型アノテーションから型を取得する
  • 型推論による型情報の取得は未実装

このプラグインを使用するには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

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

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

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

TypeScript

基本戦略は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をお待ちしております。