[TAC:21] Doxygenを使って明日の自分を困らせないようにする

はじめに

この記事はtaniho Advent Calendar 2017の21日目の記事です．

今日は，ソースコードのドキュメントを作ってくれるDoxygenの紹介をしようと思います．

Doxygenとは

「昨日の自分が書いたコードが読めない」「自分で作った関数の使い方がわからない」ということ，よくありませんか？
C言語の標準ライブラリは，インターネットで調べれば使い方・リファレンスが見つかると思います．しかしマウスで使う関数はすべて自作なので(当然のことですが)誰もリファレンスを用意してくれません．
そこで，Doxygenを使って自分でリファレンスを作りましょうというのが今日の話題です．

Doxygenで作ったリファレンスをお見せします．これは僕の前作のマウス，タニタンv2.0Hのコードリファレンスです．作ったリファレンスはLaTeXまたはhtmlファイルなどに出力できます．次の例はブラウザでhtmlファイルを表示したものです．

わかりやすいですね．マイクロマウスの場合，壁情報の格納や，壁センサ値の取得関数など，新作のマウスでも流用するコードはこういった風にリファレンスを作っておくと便利です．

リファレンスを書く

Doxygenでリファレンスを作るためには，ヘッダファイルにコメントという形でメモを残す必要があります．Doxygenで認識される代表的な形式をまとめます．

/**
 * この形式で書くと複数行コメントがDoxygenに認識される．アスタリスクの個数が重要．
 */

/// このようにスラッシュ3つのコメントもDoxygenに認識される．1行コメントの場合はこちらが便利．

// 先程のaddWall関数の説明書きの例
/**
 * @brief 壁を追加します
 * @param x 壁を追加する区画のx座標
 * @param y 壁を追加する区画のy座標
 * @param angle 今自分が向いている絶対方向
 * @param wall 今見えている壁情報
 */
void addWall(int8_t x, int8_t y, MazeAngle angle, Walldata wall);

// Map::isExistWall関数の例
/**
 * @brief 指定した方向に壁があるか返します。
 * @param dir 壁を調べたい方向
 * @return 壁があればtrue，なければfalse
 */
bool isExistWall(MouseAngle dir);

以上です．

本当はもっと色々書けることがあるのですが，個人開発のコードなので最低限これだけあれば問題ないと思います．

バグ管理

Doxygenでは関数のリファレンスだけでなく，TODOリスト・バグリストも作ることが出来ます．これは任意のソースファイルに書くと便利です．
次のようにします．

// まだ実装したい機能がある関数
void hoge() {
/// @todo これからやるべきこと
}

// バグがある関数
void fuga() {
/// @bug 暴走する
}

バグ，TODOリストはリファレンスと別ページにまとめられます．

ドキュメントを生成する

ドキュメントは簡単に作れます．

CUI

Doxygenをインストールします．

sudo pacman -S doxygen

プロジェクトのあるディレクトリに移動し，初期設定ファイルを生成します．初めに一度だけ実行します．

doxygen -g

Doxyfileが設定ファイルなので，必要に応じて書き換えます．

次のコマンドでリファレンスを生成します．

doxygen

おわりです．./html/index.htmlをブラウザで開くのが一番お手軽にチェックできます．

GUI

GUIは使っていないのでわかりません．良さそうな記事があったので，これを見てみてください．

最近覚えた便利アプリ doxygen - Qiita

まとめ

鵤くんではバグ管理にのみDoxygenを使っています．しかし，ちょっとした説明書きをコードに書くだけで見やすく整えてくれるDoxygenは非常に便利です．是非活用してください．

明日のtaniho Advent Calendar 2017も何か書きます．