jgame.jsのAPIドキュメントを書き始めた
さて、さすがにフレームワークを作っておいてドキュメント0ってのもありえないんで、javadocみたいなapiリファレンスを書き始めた。
昔はソースコードにコメント埋め込んで自動生成ってのが好きだったんだけど、特にベトナムでやるようになってからソースコード中に埋め込まれたコメントの邪魔臭さを強く感じるので、基本ソースコードは0コメント指向で*1、ドキュメントは別のを書くという方針。
ドキュメント書きはじめて気がついた点諸々。
フレームが使えなくなってた件
今更かよって話だけど、html5でフレームが使えなくなってた。
おー、javadocにしようと思ったのに出来ねぇじゃねぇか。
しょうがないのでfloatにしようかと思ったんだけど、BULLET見てもらえればなんとなく想像出来るかもだけど、width:100%が好きな人間なので、float駄目なんだよね。
はてなで使っているハックであるこれ使う事にした。
<style> #container { position:relative; width:100%; } #sidebar { position:absolute; width:200px; } #content { width:100%; margin-left:200px; } </style> <div id="container"> <div id="sidebar"></div> <div id="content"></div> </div>
今回初めて使ったけど、これ初めて考えたやつ頭いいなぁと。リスクやデメリットほぼ0な気がする。
開発環境戻ったらBULLETもresize使わないでこれに直そうと思う。
ドキュメントの書き方
まあ、ドキュメントなんて面倒なものを書く時は、どれだけ手を抜けるかを先に考える。
HTMLそのまま書くなんてありえないよねと。
じゃあどうするかなんだけど、普通はwikiっちゃうところなんだけど今macのwifiがいかれてしまっている以上ローカルですませたいので、HTML埋め込みテキストをjavascriptで拾って整形するってやり方がいいかなと。
プロトタイプ
テスト中なので後で直すかもだけど、こんな感じの謎フォーマットで書く予定。
<!doctype html> <html lang="ja"> <head> <meta charset="utf-8"> <title>jgame.js API Reference</title> <link href="api.css" rel="stylesheet"> <script type="text/javascript" src="jquery-1.8.3.js"></script> <script type="text/javascript" src="api.js"></script> </head> <body> <div id="header"> <h1>GameTimerクラス</h1> </div> <div id="container"> <div id="menu"> </div> <div id="body"> </div> </div> <div id="texts"> <div id="summary"> ゲーム内のタイマーを管理するクラスです。 通常は<a href="Game.html">Game</a>クラスのaddTimer、revemoTimerメソッドのみ利用するため、本クラスを直接操作することはありません。 </div> <div id="constructor"> var timer = new GameTimer(100); タイマーの起動間隔を指定してインスタンスを生成します。 </div> <div id="fields"> tick:number; //タイマーの前回実行時間です wait:number; //タイマーの起動間隔です trigger:Trigger; t:number;//タイマーが起動された時のwindow.getTime()の値です。 タイマー自体を表すイベントです。 100ミリ秒のタイマーであれば、大体100ミリ秒ごとに本イベントが起動します。 Gameクラスのupdateとは異なり、大体の時間である事に注意してください。より正確な時間処理を行いたい場合、GameTimerではなくupdateにより正確に時間を計る処理を作る必要があります。 --- </div> <div id="methods"> tryFire(t:number) { t:number;//今回の時間。window.getTime()の値である点に注意してください タイマーが起動条件を満たしている場合に起動します。 --- fire(t:number) { t:number;//今回の時間。window.getTime()の値である点に注意してください タイマーを起動させ、タイマーの内部時間を進めます。 --- </div> </div> <script type="text/javascript"> var summary = $("#summary").html(); var constructors = $("#constructor").html(); var fields = $("#fields").html(); var methods = $("#methods").html(); var notes = $("#notes").html(); </script> </body> </html>
サンプル。メニューのリンククリックしても、GameとIndex以外はnot foundだけど。
http://tsuge.sub.jp/sugoroku/blog/api-sample/GameTimer.html
ちなみに解釈用javascriptは相当適当なので、流用は無理。別に物好きが持っていくのは止めないけど。
今回すげーラッキーだったのは、TypeScriptを使った事で変数の型がすでについてるという点。
全体的に戻り値に型指定を忘れていたから、戻り値は別途コメントしないといけないけど、ソースコード直接コピペで型と変数名がなんとかなったのは大分楽になった。
この手の生成ツールって、本当はnode.js辺りで動くscript書いて、HTML埋め込みじゃなくて静的に生成した方がSEO的にも、各種ブラウザへの優しさ的にも、jqueryをコミットしなくてよいという辺りでもあらゆることでいいんだけど、ネット貧乏なのでnode.jsについて調べるのが時間かかるって事で許してもらおうと。
しかしドキュメントは時間かかる。。
どれだけ手を抜く形にしようが、どうしてもそれなりに書く必要があるのでドキュメントは時間かかっちゃうね。
フレームワークは三日でかけても、ドキュメントも入れると２日追加でかかって、なんだかんだで仕上げるまで一週間って感じ。
で、一回作ると今度は保守が必要になって、プログラムの更新と同時にドキュメント更新も必要になる。
それを最小限に抑えるための仕組みとしてjavadocが出来て、そこからソースコード内にいっぱいドキュメント書こうってのが当たり前になったけど、冒頭に書いた通り俺はソース内のコメントが嫌いなのでこれは却下。
ソースとドキュメントをなんとか同期したい気はするけど、せいぜいチェックツールでインターフェースがドキュメントと合ってないかチェックするくらいしか出来ないわな。
結局、フレームワーク類はある程度のレベルのやつなら誰でも開発出来るし実際星の数程*2あるんだろうけど、普及させるためにはこの手の保守コストがでかすぎて廃れちゃうんじゃないかなぁという気がする。
俺も多分、最低限書いて、後はプログラム更新してからドキュメントはバージョンずれてても気にせずやる形になると思われる。
あくまでフレームワークは副産物で、ゲーム作成のために必要だから作ったんだし、目的を忘れないようにしたいなということで。
こういう手間を惜しまないやつが勝つんだろうというのはなんとなく想像出来るけど、敗者になろうが俺はゲーム作りたいんじゃー。
