「Haxeに対応したドキュメント吐き出しツールはないものか…」と適当に探し回ってたら公式でこんなのがありました
Haxeの公式ドキュメント
http://api.haxe.org/
とかHaxeFlixelの公式ドキュメント
http://api.haxeflixel.com/
と同じような体裁のドキュメントを吐き出すためのツールで、
いわゆるDoxygenみたいな、ソースコードドキュメンテーションシステムの一種だそうです
今回はコレを使って、HaxeFlixelのプロジェクトからAPIドキュメントを吐き出す手法をメモります
環境
- Windows
- HaxeFlixel 4.1.1
- dox 1.1.0
インストール
コマンドプロンプトから
haxelib install dox
HaxeFlixel プロジェクト側でやること
普通のhxmlプロジェクトと同様、ドキュメントhtml生成用のxml生成から最終的にdoxに流す流れ自体は同じです
ただし、HaxeFlixelプロジェクトの場合hxmlがない(?)のでxml生成指示をProject.xmlに書き込むのが違うところ
Project.xmlに以下のパラメータを挿入します
<haxeflag name="-xml" value="bin/doc.xml" />
※
valueに書くpathについては自由に決めてよいです
ちなみに、フォルダが存在しなかった場合は勝手に作られます
dox の実行
上述のパラメータを挿入した状態でビルドを行うとプロジェクトフォルダ下のbinフォルダにdoc.xmlが作成されるので、
コンソールでプロジェクトフォルダまで移動して以下のコマンドを実行します
haxelib run dox -i bin -o bin/pages
-i の後ろには生成したxmlファイルのおかれているフォルダを、
-o の後ろにはこれから生成するhtmlドキュメント群を置くフォルダを指定します(これもフォルダがなかったら勝手に作られます)
処理中メッセージが出るのでしばらーく待つと Done. と出てきます。生成完了です
bin/pages に行くとなんかわんさかhtmlやらなんやらが吐き出されてます
index.htmlを開いてHaxeFlixelのAPIドキュメントページなんかでよく見る体裁のページが出てきたら成功です
後は開発を進めて増えていくドキュメントに思いを馳せましょう
おまけ: 書式
説明を入れたいクラスやらなんやらの上に
/**
**/
とか
/**
*
*
*/
で囲んだ文章を入れると説明文としてドキュメントに挿入されます
書式としてはgithub-flavored markdownが使える（？）ようです
（ただ、基本的な構文は概ね動くようですが、箇条書きがあまりうまく動いてないような気もします）
@param Object1 hogehoge
@return hogehoge
javadoc風のパラメータ説明書式にも限定的に対応しているようです
おまけ: フィルタリング
ドキュメント生成時、-inまたは-exのパラメータにパッケージ名をつけて流すことで生成ドキュメントに含める含めないを選択することができます
-in game -in flixelとかやるとgame以下のパッケージとflixel以下のパッケージのみがドキュメント化され、
-out cppとかやるとcpp以下のパッケージのみが除外されたドキュメントが出来上がります
自分が書いたやつはドキュメント化したいけどライブラリまでドキュメント化されるのはちょっと…という人も安心（？）
ちなみに、依存先のライブラリがドキュメント化されてなくても、
該当クラスの名前から直接詳細に飛べない程度で、ドキュメントとしての体裁が崩れることはありません たぶん
オプションはここにいろいろあるようです
https://github.com/HaxeFoundation/dox/wiki/Commandline-arguments-overview
もっと色々機能はあるようですがまだあまり眺めきれてないのでひとまずこのへんで
感想
最初のパラメータ指定でちょっとハマりましたが、そのあとはサクサク進めて非常に楽にドキュメントが生成できました
Jenkinsなんかと組み合わせて、アプリのビルドと一緒にドキュメント更新とかやれると色々と捗るのではないかと思ったり思わなかったり