DoxygenにVB - vbfilter(awk)

(2008/1/25追記)単にvbfilterの使い方を見たい場合は、別の記事にまとめてますのでそちらをどうぞ。

Doxygenはドキュメンテーション・システムという種類のソフトで、プログラムのソースファイルを解析して、ファイルや変数や関数の一覧や、インクルードや呼び出しの関係図などを含んだ文書を作ってくれます。さすがに説明の文章までは自動的に作ってはくれませんが、予め決まった形式でソースファイル内に説明文を入れておいて、Doxygenに掛ければ立派な仕様書一式が出来上がります。

Doxygenの本来の用途はこのような文書生成なのですが、もうひとつの側面として、他人の作ったプログラムの解析にもたいへん役立ちます。設定次第では、関数やファイルの依存関係の図やら、図から対応する説明へのリンクやら、説明からソースの対応する部分へのリンクやらといった、充実した参照機能を備えたHTMLドキュメントを作ることが出来るので、場合によっては開発環境のエディタで見るより便利です。私も以前、開発中の業務用システムのパフォーマンスの検証を、実機が使えない状況でソースとログを突き合わせて机上でやる羽目になった時、他人が開発を担当した部分を理解するのにとてもお世話になりました。

というわけで、もうじき他人の作ったソフトの機能追加の仕事を受ける予定があるもので、もらったファイルをとりあえずDoxygenに掛けてみるべ、と思いたちました。

ところがここで問題がひとつ。今回の案件の開発言語はVisual Basic 6.0なのです。DoxygenはC++やJavaなど向けで、VBはそのままでは使えません。

Doxygenの公式サイトに行ってみると、ダウンロードのページに"Helpers tools & Scripts"という項目があり、別のページへ誘導されました。移動した先のページには、様々な機能追加のツールが用意されてます。標準で対応してない言語のための機能追加のところに、VB向けのものが2つありました。どちらも同じvbfilterという名前です。1つはawkのスクリプトで、もう1つはPythonのスクリプトです。awkのスクリプトの方には追加で必要なツールがありますが、その入手先も示されてます。とりあえず両方ダウンロードしておきました。

まずはawkのスクリプトの方を試してみることにします。

付属の説明を読むと、sh.exeとtee.exeとawk.exeをvbfilterと同じディレクトリに配置して、そのディレクトリのフルパスを引数として、DoxygenのINPUT_FILTERにvbfilter.batを設定するようにとあります。

ここで一つ注意事項です。vbfilterのパスには空白を含まないようにとのことです。Program Filesの下に置くのはダメということですね。

vbfilterを適当なところに配置し、Doxywizardを起動し、ソースファイルを処理するための設定を一通り行い、設定を保存して実行します。

HTMLファイル一式が出来たので、開いてみます。……ファイル名一覧が出来てますが、それ以外のものがありません。
Doxywizardのメッセージを遡ってみると、「『'』の片割れを見つける前にファイルの終わりにきた」というようなことが書かれてます。

……「'」といえば、Basicのコメント記号ですよ。処理に失敗してる？もしかして、vbfilterは「REM」だけ処理して「'」は処理しない？

試しに1つのファイル中の「'」を全部「REM 」に書き換えて、vbfilter.batを単独で起動してみます。……相変わらず同じメッセージが表示されます。もうソース中に「'」は無いはずなのに。それよりも、Basicでは「'」は引用符じゃないんだから、ペアの片割れという扱いをされるのはおかしいです。vbfilter.batの中に問題がある？

vbfilter.batをメモ帳で開いてみました。awkで第2引数のソースを処理するというコマンドを引数として与えてsh.exeを起動する仕組みになってます。コマンド文字列の引数は「"」で囲まれてます。……あれ？これだと第2引数(処理対象のファイル名)が「"」で囲まれてたらまずいのでは。処理対象のソースも、パスに空白を含まないところに配置しないといけないということですか。

ファイルを移動して、Doxygenの設定を変更して、再実行します。……今度は成功です。出来上がったドキュメント内には変数や関数もしっかり記載されてます。ですが、依存関係等の図が一切ありません。

再度vbfilter.batを単体起動してみました。処理結果のファイルを元のファイルと比較してみると、関数やサブルーチンの先頭部分だけが取り出されて、C++の関数プロトタイプのように整形されていました。処理の中身はバッサリ捨てられてます。これでは、本来のドキュメント生成という目的は果たせても、解析には使えません……orz

Python版はまた今度。