no-image

DoxygenとGraphvizでコードのドキュメントを自動生成する

OSSのコードリーディングの為にドキュメントを自動生成したり、
共同開発のために簡単にドキュメントを作成できるツールにDoxygenというのがあります。

 

ドキュメント生成ツールはいくつかあるのですが、
DoxygenはC++、C、Java、Objective-C、Python、IDL、Fortran、VHDL、PHP、C#など色々な言語で使えるので言語の混じったプロジェクトを作っている場合に便利です。

 

今回使用する環境はmacです

$ sw_vers
ProductName: Mac OS X
ProductVersion: 10.13.4
BuildVersion: 17E199

 

公式ドキュメント

 

日本語です。
大まかな流れが載っています。

 

【参考】Doxygen

 

Doxygenのインストール

 

コマンド一発でインストールできます。
$ brew install doxygen

 

今回はコマンドラインからインストールしましたが、
デスクトップアプリもあるので、そちらを利用したい場合は以下の記事を参考にしてみてください。
【参考】最近覚えた便利アプリ[doxygen] – Qiita

 

Graphviz

 

doxygenの設定をいじる前にGraphvizをインストールしておきます。
これは、dot言語という言語でグラフを作成するソフトです。
以下のコマンドでインストールすることができます。

$ brew install graphviz

 

Doxygenの使い方

 

目的のコードがあるところへ移動し
$ doxygen -g

 

コレを実行するとプロジェクト内にDoxyFileが作成されます。

 

atomパッケージ

 

doxyfileを編集する前にエディタにatomを使っている方はパッケージを入れてみましょう。
doxyfileをシンタックスハイライトしてくれるパッケージです。
【参考】language-doxygen

 

DoxyFileの編集

 

DoxyFileでプロジェクト名や言語、どのファイルを対象にドキュメントを作成するかなどを設定することができます。

 

設定項目はめちゃくちゃ沢山あるのですが、
今回は僕は以下の項目を編集しました。

 

こんな感じのテンプレで紹介します・
項目名: 初期値→編集後
この項目の設定の概要

 

PROJECT_NAME: “”→プロジェクト名
プロジェクト名を変更します。

 

OUTPUT_LANGUAGE: English→Japanese
ドキュメントの言語を設定できます。

 

CREATE_SUBDIRS: NO→YES
出力にサブディレクトリを使用します。

 

RECURSIVE: NO→YES
サブディレクトリを管理対象に含めるかどうか。
ディレクトリ配下を再帰的にスキャンするか

 

HAVE_DOT: NO→YES
Graphvizを使うかどうかです。

 

CALL_GRAPH: NO→YES
メソッド呼び出し関係図を生成するかどうか

 

CALLER_GRAPH: NO→YES
被メソッド呼び出し関係図を生成するかどうか

 

EXTRACT_ALL: NO→YES
コメントがなくても、要素をすべてドキュメントに出力

 

REFERENCED_BY_RELATION: NO→YES
その関数を参照する関数をリストします。
REFERENCES_RELATION: NO→YES
その関数が呼び出したり使っている要素をリストします。

 

割と多くの項目について解説されている記事がありました
【参考】Doxyfile(基本的な設定) — Algo13 2016.12.17 ドキュメント

 

実行

 

Doxyfileがあるディレクトリで以下のコマンドを実行すると、ドキュメントが生成されます。
$ doxygen

 

その後、できたhtmlフォルダの中からindex.htmlをブラウザで開くとドキュメントを参照することができます。

 

コメントの書き方

 

Doxygenでは、その関数の使い方などをコードの中にコメントとして記述しますが、
このときにある定式に則って書いていくと、良い感じにドキュメントに表示されます。

 

そのコメントの書き方はプログラミング言語によって若干異なるので、
適宜調べてみてください。

 

以下では、Pythonでのコメントの書き方を一部紹介します。

 

公式ドキュメントにかかれている方法とちょっと違った書き方がStackOverFlowで紹介されていたので、そっちを使っています。
どうやら@breifの前に感嘆符を付けると良いみたいですね。

 

関数内にコメントを加える場合は以下のような感じです。

 

briefにその関数の大まかな説明である要約を書き、
@paramの後に引数、
@retrunの後に返り値などを記述します。

 

関数やクラスの宣言の近くに書かない場合は
@fnなどを付けて、コメントを付けることもできるようですが、
コードの可読性に欠けると思うのであまりおすすめできません。

 

これらの、briefやparam以外にも同じ様なコマンド幾つかあります。
一気に覚えるのは大変なので、適宜調べながら覚えていくのが良さそうです。

 

【参考】
Doxygen – 特殊コマンド
Doxygen入門の入門 – Simple IT Life

 

そのた

 

その他、大まかにドキュメントを作るにあたってどうすれば効率良くできるのかなどは色々な人が考えているようです。
面白かったものを2つ共有しておきます。

 

【参考】
ドキュメント書くのを限界までラクにする – Qiita
(´・@・)タコヤ!!! Doxygenのコメントを限界まで減らそう