くまくまの業務日誌

Markdown記法で徒然に書いてみましょう。

Doxygenについて

Doxygenについては、以下の検索をたどってみてください。

本当にこのような高度なレベルのドキュメント生成機能を"GNU General Public Licence"で使わせて頂いていいのかと平身低頭になる強力な解析支援ツールであります。

既に多くの方が使い方、Tipsなどをアップされているので、今さら私がなにかをお伝えするよりも、検索した情報の方が有用ではないでしょうか。

ちなみにですが、Doxygenにお世話になる場合というのが、以下のシチュエーションが多いのが私の実情であります。

  • 基本設計書、機能設計書までは、利用者と設計者の意思疎通、つまり「こうして欲しい」とか「こういう仕組みで動かすのです」という内容をお互いにレビューして鍛え上げていくのに対して、詳細設計書など、プログラムの構造を主に説明する資料に関しては「作っといて」とか「欲しいです」など、成果物の一つであるがために要求され、こちらも時間をかけずに体裁の整った資料を作成するために、Doxygenを利用する。
  • パラシュート部隊よろしく、炎上現場に放り込まれるも、資料も管理者もしっちゃかめっちゃかで、なにも情報がないままソースコードだけがあるので、Doxygenでまずは全体像をつかんで、内容を把握する。

このような「納品用」のドキュメント作成ツールは他にも・・・

などを使わせて頂きました。どれも本当に助けて頂きました。しかし、正直なところですが、関数レベルの設計書のニーズに関して、納品物としてではなく、問題発生時の解決の糸口として活用していきたいのが本音ではあります。設計書を見て、「ここがまずかったですよね。」と指摘してくださった方は皆技術と管理に長けたすごい人たちばかりでしたので。

さて、話はDoxygenに戻りますが、Doxygenの出力する内容は関数の構造だけでなく、例えばクラスに関しては、その継承関係図も出力してくれます。ちなみに、下の図は私の作成中のライブラリの継承関連図です。曲線の矢印が美しい図面であります。

f:id:kumakuma0421:20201115232631p:plain
alt::WindowsLibraryの継承関係図

あと、「呼出し関連図」と「被呼出し関連図」も出力する事ができます。

f:id:kumakuma0421:20201115233308p:plain
呼び出し関連図

f:id:kumakuma0421:20201115233334p:plain
被呼び出し関連図

これらの関連図が活躍するのは、「ここをいじった時にどこが影響する(=再試験の対象になる)のかを見積もる(または、別の方法を考える)場合に有効です。さすがに、「やるぞ」と決めた時は、関連するキーワードでGREPする結果の方が正しいとは思いますが。

で、本日は自分が作成中であるライブラリに対して久しぶりにDoxygenの出力結果を確認してみようと思って、色々設定をいじりながら「これが私のベストかな」と思う設定にたどり着きました。いつも、思い付きで設定ファイルをいじってたまに新しい発見をしたりしますので、あまり固着しない方がいいのかなとも思いますが、最初のスタートラインにするファイルでいつもそう設定している、というファイルがあるのはスタートダッシュも早いですので。

ちなみに今回の(既に皆さんは知っている)発見は・・・

  • ソースがSJISだったので、いつもツールでUTF-8に変換していたのですが、DoxygenはSHIFT-JISと伝えてもうまく変換できません。実は"CP932"だったのです。今日は本気で「面倒くさいなぁ」と思ったので、ここにたどり着きましたが、いつもお客様の「面倒くさいなぁ」を解決する側(私が面倒くさい作業を行うと、お客さまが楽になる)でしたので、面倒くさいに耐性ができてしまって、困ったものです。
  • GitHubにはGitHub Pagesなるものがあり、静的なHTMLならWebホスティングできるそうです。これって、Doxygenの出力結果格納にピッタリではありませんか?で、置きました。しかし、一部のファイルがうまく表示されません。「そのうち表示されるようになるだろう」と高を括っておりましたが、一向に表示される気配はなく、これまた本気で「なんで?」を探してみたところ、GitHub Pagesはアンダースコアで始まるファイルは対象外、というオチでした。対処方法も、「.nojekyll」ファイルをルートに置くだけで良いらしく、指示通りにファイルを配置したら、きれいに見れるようになりました。

本日は、Doxygenでいろいろ格闘した訳でありますが、Doxygenは、まだ奥が深い技術を持っていそうで、修行不足を痛感するこの頃であります。本日使った図表、Doxygen設定ファイルなどは、ここに格納しておりますので、もしよかったらご覧になってみてください。