Doxygenでコードを読む

仕事や遊びで他人の書いたコードを読むことがよくあります。そういう場合、私はDoxygenを使います。Doxygenはコードに適切なコメントをつける事で、強力な文書を生成するためのシステムです。生成されたドキュメントはきちんと定型になるほかに、HTMLによってクリッカブルなソースとしても機能するようになります。
そこで、他人が作ったドキュメントに自分でDoxygenコメントをつけて行くことで、文書を育てながら自分の理解を深めていく、というのが私の好みの方法です。
たとえば、最近ちょっと興味のあったWindows Media Player用のDSP Plug-in。これはWizardがMicrosoftプログラマが書いたコードをスケルトンとして生成します。そのため、そこそこコメントは付いていますし、Web上にちゃんとしたドキュメントも用意されています。が、ソースとドキュメントを並べてみてもいまいちピンときません。
そこで、私は次のようにします。
1.ソースをDoxygenにかけて、クリッカブル・ドキュメントを生成する。
2.生成されたドキュメントを追いかけて、MSのドキュメントと見比べる
3.分かったことをソースにDoxygenコメントとして追加する
これを繰り返していくと、分かったところから文書が生成されていきます。ざっと見返して文書ができていない部分はまだ理解していないところです。忘れてしまってもDoxygen文書ができていますからすぐに調べなおして思い出すことができます。
WMPのPlug-inの場合、途中で生成されたクラスがCOMのインターフェースとして機能していることに気づき*1APIの文書をコピペできました。APIをコピペして作ったDoxygen文書はMSの著作権を侵害しているため、外部に公開することはできません。しかし、作り上げる過程で呼び出し側(WMP)と呼び出される側(Plug-in)がどう働くか、とてもよく理解できました。さらに、MSのAPIにないメソッドは、内部の作業用だとすぐに理解できました。
せっかく文書を作っても元のコードが改変されると元の木阿弥です。しかし、非常に理解が楽になるのでこの方法はとても重宝しています。Doxygenには高木さんによる日本語サイトがあり、いつも助けられています。

*1:私はこれまでCOMプログラムを読んだことも作ったこともないため、気づくのが遅かった

/* -----codeの行番号----- */