macOSでDoxygenを使ってC,C++ソースコードからドキュメントを作成する

投稿者: | 2017年12月21日

はじめに

Githubなどにあるソースコードを解析する際に、ファイル構成やクラス構成などの概要だけでも分かれば解析のアタリがつけやすいです。本来は一定のルールに従ったコメントを記述したソースコードからドキュメントを自動生成するツールであるDoxygenを解析のために利用します。

解析が目的なので、対象のソースコードは変更しません。また、Doxygenの設定も難しいことは考えずに必要な情報が得られた設定だけメモしておきます。

追記

Graphvizをインストールすると、関数のコールグラフやクラスのUML表現が可能になります。このコールグラフが解析に非常に有用なので、Graphvizの設定も追加します。

環境

macOS 10.12.6

Doxygen 1.8.13_1

Graphviz 2.40.1

インストール

macOSならば、DoxygenとGraphvizをhomebrawによりインストールできます。

ringo@stupiddog $ brew install doxygen
==> Downloading https://homebrew.bintray.com/bottles/doxygen-1.8.13_1.sierra.bottle.1.tar.gz
Already downloaded: /Users/stupiddog/Library/Caches/Homebrew/doxygen-1.8.13_1.sierra.bottle.1.tar.gz
==> Pouring doxygen-1.8.13_1.sierra.bottle.1.tar.gz
🍺  /usr/local/Cellar/doxygen/1.8.13_1: 9 files, 13.1MB

ringo@stupiddog  $ brew install graphviz
==> Installing dependencies for graphviz: fontconfig, libtiff, webp, gd
==> Installing graphviz dependency: fontconfig
...
==> Pouring graphviz-2.40.1.sierra.bottle.1.tar.gz
🍺  /usr/local/Cellar/graphviz/2.40.1: 536 files, 12.9MB

利用方法

Github – Adafruit-ST7735-Libraryから取得したコードを例にします。

対象のプロジェクト内にファイルを作成しない方法でドキュメントを生成します。

ringo@stupiddog  $ pwd
/Users/stupiddog/src

ringo@stupiddog  $ git clone https://github.com/adafruit/Adafruit-ST7735-Library
Cloning into 'Adafruit-ST7735-Library'...
remote: Counting objects: 461, done.
remote: Total 461 (delta 0), reused 0 (delta 0), pack-reused 461
Receiving objects: 100% (461/461), 146.80 KiB | 269.00 KiB/s, done.
Resolving deltas: 100% (198/198), done.

ringo@stupiddog  $ ls -l ./Adafruit-ST7735-Library/
total 80
-rwxr-xr-x  1 stupiddog  staff  24382 12 21 12:38 Adafruit_ST7735.cpp
-rwxr-xr-x  1 stupiddog  staff   5565 12 21 12:38 Adafruit_ST7735.h
-rw-r--r--  1 stupiddog  staff   1260 12 21 12:38 README.txt
drwxr-xr-x  7 stupiddog  staff    238 12 21 12:38 examples
-rw-r--r--  1 stupiddog  staff    319 12 21 12:38 library.properties

設定ファイルの作成

まずdoxygen -gコマンドにより設定ファイルの雛形を作成します。カレントディレクトリにDoxyfileとして作成されます。

ringo@stupiddog  $ doxygen -g


Configuration file `Doxyfile' created.

Now edit the configuration file and enter

  doxygen Doxyfile

to generate the documentation for your project

ringo@stupiddog  $ ls -lF
total 216
drwxr-xr-x  9 stupiddog  staff     306 12 21 12:38 Adafruit-ST7735-Library/
-rw-r--r--  1 stupiddog  staff  107461 12 21 12:42 Doxyfile

設定ファイルの変更

デフォルト設定ではカレントディレクトリにあるソースを対象としサブディレクトリは対象としません。今回はカレントディレクトリのサブディレクトリに対象のプロジェクトがあります。

また、html形式とLaTeX形式のドキュメントが作成されますが、LaTeX形式は不要です。

ringo@stupiddog  $ tree ~/src
/Users/stupiddog/src
├── Adafruit-ST7735-Library
│   ├── Adafruit_ST7735.cpp
│   ├── Adafruit_ST7735.h
│   ├── README.txt
│   ├── examples
│   │   ├── graphicstest
│   │   │   └── graphicstest.ino
│   │   ├── rotationtest
│   │   │   └── rotationtest.ino
│   │   ├── shieldtest
│   │   │   └── shieldtest.ino
│   │   ├── soft_spitftbitmap
│   │   │   └── soft_spitftbitmap.ino
│   │   └── spitftbitmap
│   │       └── spitftbitmap.ino
│   └── library.properties
└── Doxyfile

7 directories, 10 files

ほとんど設定を変更せずにドキュメント生成できますが、以下の設定を変更します。

  • サブディレクトリまで検索対象とする(RECURSIVE = YES)
  • LaTeX形式の出力はしない(GENERATE_LATEX = NO)
  • 解析なのでプライベートメンバーなど全て抜き出す(EXTRACT_ALL = YES)
  • ソースコードのクロスリファレンスを生成(SOURCE_BROWSER = YES)
  • インクルードファイルのコードもドキュメント化(INLINE_SOURCES = YES)
  • Graphviz(dotコマンド)がある(HAVE_DOT = YES)
  • クラス継承図とコールグラフをUML形式で表す(UML_LOOG = YES)
  • 呼び出し側、呼び出し元のグラフを作成する(CALL_GRAPH = YES, CALLER_GRAPH = YES)

以下がdoxygen -gで作成したDoxyfileDoxyfile.defaultとして複製し変更箇所を確認した結果です。(左が変更後、右が変更前)

ringo@stupiddog  $ diff -y --suppress-common-lines -W80 Doxyfile Doxyfile.default 
EXTRACT_ALL            = YES	      |	EXTRACT_ALL            = NO
RECURSIVE              = YES	      |	RECURSIVE              = NO
SOURCE_BROWSER         = YES	      |	SOURCE_BROWSER         = NO
INLINE_SOURCES         = YES 	      |	INLINE_SOURCES         = NO
GENERATE_LATEX         = NO 	      |	GENERATE_LATEX         = YES
HAVE_DOT               = YES	      |	HAVE_DOT               = NO
UML_LOOK               = YES	      |	UML_LOOK               = NO
CALL_GRAPH             = YES	      |	CALL_GRAPH             = NO
CALLER_GRAPH           = YES	      |	CALLER_GRAPH           = NO

実行

doxygenコマンド実行時に Doxyfileを指定しなければカレントディレクトリにあるDoxyfileが読み込まれます。

ringo@stupiddog  $ ls -lF
total 216
drwxr-xr-x  9 stupiddog  staff     306 12 21 12:38 Adafruit-ST7735-Library/
-rw-r--r--  1 stupiddog  staff  107463 12 21 13:06 Doxyfile

ringo@stupiddog  $ doxygen 
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for msc files...
Searching for dia files...
Searching for files to exclude
Searching INPUT for files to process...
Searching for files in directory /Users/stupiddog/src
Searching for files in directory /Users/stupiddog/src/Adafruit-GFX-Library
Searching for files in directory /Users/stupiddog/src/Adafruit-GFX-Library/fontconvert
Searching for files in directory /Users/stupiddog/src/Adafruit-GFX-Library/Fonts
...
finished...

結果の確認

結果はhtmlディレクトリに出力されます。

ringo@stupiddog  $ ls -lF
total 216
drwxr-xr-x   9 stupiddog  staff     306 12 21 12:38 Adafruit-ST7735-Library/
-rw-r--r--   1 stupiddog  staff  107463 12 21 13:06 Doxyfile
drwxr-xr-x  44 stupiddog  staff    1496 12 21 13:13 html/

html/index.htmlをブラウザで開くと生成されたドキュメントを確認できます。

ringo@stupiddog  $ open html/index.html

まとめ

クラスのリストや継承階層、ソースコードのクロスリファレンスなどをhtml形式で取得でき、関数の呼び出し関係もグラフ化できるので解析には十分です。一定のルールに従ったコメントを付けていれば、自動生成の対象になるので、自分のコードもDoxygenに対応させるのがよさそうです。