29 September '2003 - 23:35 | 雑記 一石二鳥。
「ドキュメントはソースです。バグも書いてありますし。」 こう言えたらいいのだけれど、そうは問屋が卸さない。自分が仕事用に開発したライブラリがいくつかあるのだが、主に自分がかかわるプロジェクトでメインで使うライブラリだし、社内でこのライブラリを使う人たちは、自分ともプロジェクトの関係が近い人が基本だから、ドキュメントは適当にでっち上げたのしかなく、しかも、どうしようもないことに、ドキュメントはあまりまじめに保守してなかった。
が、しかし、どうも、最近、それを売ってくれという話が来たりするようになった。
ただ、ライブラリそのものを売ることを前提には書いてないし、ドキュメントも不備だったりして、正直、面倒くさいなぁ、とは思うのだが、欲しい人を探して売ってしまうというのは、商売として正しいし、エンジニアとしてはセールスの人の言うことを聞くしかない。
というわけで、ドキュメントの保守をちゃんとすることにしたのだけれど、まじめにやるとなったら、やっぱり、JavaDoc みたいな方向がいい。これなら、ちょっとだけまじめやれば整合性は完璧だし。
で、書式を覚えるのも面倒だし、方向だけでなく、書式も JavaDoc のまま、もしくは類似のものがいいなぁ、ということで探してみた。
すると、C++ で使えるものは多いんだけれど、C でもいいよ、というのはほとんどない。また、C で使えるんだけれど、書式は独自というのがほとんど。
おれが書いてるライブラリは全部 C で書いてるので、JavaDoc みたいなスタイルというと、実はそんなになかったのだった。
結局 Documentation Tools を参考にして、Doxygen を使ってみることにした。使ってみたら、これがなかなかいい。かなり気に入った。
こいつの存在自体は前から知ってんだけれど、あまり興味をもってなくて何も調べてなかった。不覚すぎ。
さて、こうなると、既存のライブラリのドキュメントを一新したくなる。まぁ、基本的なことはそもそもソースにもちゃんと書いているので、それを元にフォーマットを合わせればいいだけなので、言うほどひどい仕事ではない。
が、しかし、こういう面倒なことは、スクリプトを書いて計算機にやらせてしまうか、やらせることで経験値をあげることができそうな若者にやらせてしまうのが、おれ流。
そして、ちょうどいいところに、理解させとくと後でおれが楽できそうだ、というヤツがいたので、そいつにやらせることにした。「まず、このライブラリが何をやってるのか、完璧に理解し、そして、ちゃんと理解したことを証明するために、Doxygen で素晴らしいドキュメントが生成されるようなコメントを書いてみろ」と指示。
いやぁ、労せずして、それなりのドキュメントが出来上がってきて嬉しい、嬉しい。
そいつがコメントを入れる過程で散々質問攻めにあったおかげで、そいつのコード、プロトコル、仕様などの理解度もよく把握できたし、ついでにいろいろと教えてやることもできたし、ほんと、一石二鳥とはこのことだ。