投稿日:

    カテゴリー 技術 / デザイン / 制作タグ

    Doxygen + Graphviz を使ったドキュメント自動生成

    まいど。制作部のコダマです。

    自身の記事を見返してみると、エンジニアっぽい記事の投稿数が少ないので、これではいかんと言う事で、社内にも展開したドキュメント自動生成ツールを記事にしてみます。

    ドキュメントって、ハッキリ言って書くの面倒です。特に納品物の対象から外れやすい詳細設計書は、あってもメンテナンスが全く追いつかない事が多くて役に立たず、結局は「ソース読め」となる事が殆どと言うのを経験されているのは、自分だけではないはずです。

    じゃあ、ソースを読むとなっても、ポリシーをもって整理された可読性の高いソースであれば良いのですが、何がしたいのか書いてあることが分からないようなゴミ、もとい難読化されたソースを読むのは非常に苦痛ですし、そもそもスキルレベルがあんまり高くない人には、作業自体が難しいことになります。

    で、最近仕事では、そう言った状況を助ける為のツール「Doxygen」で、ドキュメント自動生成して、ソースの解析などの負荷軽減を行なっています。こいつの何が良いって、「無償で使用可能」「ソースをリバースエンジニアリングして生成」「画一化されたドュメントを自動生成」してくれるところです。設定してしまえば、あとは勝手に小人さんがやってくれるなんて、何て楽なんでしょう。

    では、折角なので、昔 Microsoft の開発ツール等に付属していた WinDiff のソースが、GitHub に公開されているので、こいつをベースに個人的にリネーム+日本語化+αしたものになりますが、出力してみましょう。

    個人的に慣れた環境なので、Windows 版を使いましたが、設定直後は斯様な感じです。理解の助けになる相関図とかも出力したかったので、「Graphviz」なるツールも事前にインストール済みの環境になります。また、細かい設定については、書いていくと結構な量になることから、今回は割愛させていただきます。

    で、Run タブの「Run doxygen」ボタンを押したら、あとは出来上がりを待つだけです。

    と、こんな感じで finished が表示されれば生成完了ですが、生成には結構結構時間がかかります。設定にもよりますが、Graphviz を使った相関図の生成が結構重い処理になるので、規模が大きいシステムの場合、空いているマシンでやるか、退社直前に開始させるとかの方が良いかもしれません。

    左下の Show HTML output ボタンを押すか、出力先の html フォルダー配下にある index.html をブラウザーで表示させれば生成されたドキュメントが確認できます。

    こんな感じでクラスの中身とか…

    呼び出し関係図のノードにリンクで遷移可能だったり…

    こうやって、ソースでも定義場所とかバルーンで表示+リンク表示されます。統合開発環境とかない場面でソースを読まなければならない場合、圧倒的に楽です。

    こんな感じで依存関係も分かります。

    Jenkins と組み合わせて、本番リリースのたびに Doxygen を実行させれば、ドキュメントのメンテナンスも自動化できると思います。もう、ドキュメントがない、ドキュメントが最新化されていない、ドキュメントの作成 or メンテコストがない、なんて言わなくて良いかもしれません。

    一つ注意なのが、Javadoc と一緒で、ソースにコメント書いていないと、結構寂しい結果になります。開発プロジェクトに組み込むのであれば、せめてメソッドヘッダーくらいは書いておくくらいの癖、もしくはルールくらいは付けた方が良いかと思います。

    では。


    関連記事

    まだデータがありません。