SML のドキュメント生成ツール SMLDoc をサルベージした
SMLDoc は SML# プロジェクトの一部として開発されていたドキュメント生成ツールです。
SMLコードのコメント中に書いた内容を、そのコメントに対応するエンティティに紐付けて表示するようなHTMLを生成します。
昔の SML# には SMLDoc が同梱されていましたが、.smi ファイルが必要になったタイミングで(?)提供されなくなっていました。
今回 SML# 0.9 から取り出してきたコードを SML/NJ と MLton でビルド出来るようにして smlsharp/SMLDoc に公開しました。
インストール
以下のようにするとビルド;インストール出来ます*1。
// MLtonの場合は // export MLB_PATH_MAP=/path/to/mlb-path-map $ make -f Makefile.(smlnj|mlton) install
Example
実際の生成例は公式サイトにあります > SMLDoc/doc/api。
自分で生成してみたい場合は smldoc-doc ターゲットを実行するとこれと同じHTMLが doc/smldoc 以下に生成されます。
$ make -f Makefile.(smlnj|mlton) smldoc-doc
(実はサルベージした方のプロジェクトでは Basis ライブラリのエンティティにも正しくリンクできている点が違ったりします。int型とかクリックしてみると分かります。)
使い方
コメントを書く
例えば関数のパラメータについての説明なら@paramと書いて名前と説明を書きます。
私の作っている SHA3 の実装 ではこんな風に書いてあります。
(** * Hash a string * * @params kind m * @param kind kind of hash * @param m input message string * @return hashed string *) val hashString : Sha3Kind.t -> string -> t
まぁ見たままですね。
詳しい使い方は OVERVIEW_ja.txt を見て下さい。
