今回初めてがっつりDoxygenを利用したので、内容をまとめます。
基本はこちらの記事を参考にしています。
インストール
インストールに使ったPCはWindows 10です。どのversionでも大筋変わらないと思います。
doxygen本体
こちらの、自身のOSに合ったものを入れてください。私はdoxygen-1.8.14-setupを使いました。
Graphviz - Graph Visualization Software
出力されたファイルに、この関数がこの関数を呼んでるみたいな関連図が出力されるようになりカッコよくなるので、こちらもオススメです。こちらからOSに合うものをインストール。
使い方
概要
簡単な手順はこんな感じ。
- Doxygenルールに乗っ取り各ソースコードにコメントを入れる。
- Doxygenに設定を行う。
- ドキュメントを出力する。
以降はこの3点を以下の流れで説明していきます。
- 基本コメントルール
- Doxygenを使ってみよう
- コメントルール補足(特に困ったもの、便利だなと思ったものを抽出して記載します。)
基本コメントルール
基本は/**, /*!のコメントから始まるコメントに反応して、その直後の変数や構造体に情報を付加することが出来ます。
今回利用したものを記載。言語はCです。
| オプション | 概要 | Doxygenに必須か？ | 備考 |
|---|---|---|---|
| @file | ファイル名を記載 | Yes | これがファイルの先頭にないとファイルがスキップされる。 |
| @brief | 概要の記載 | ? | 説明には基本これを使うので、無いと寂しいことになるかと |
| @struct | 構造体記載 | No | 何かのマネをして使ったが、効果は不明 |
| @param | 関数の引数で使用。引数の詳細が記載できる。 | No | ないと関数の引数説明が出てこないだけ |
| @return/@retval | 関数の戻り値で使用。複数の場合はretvalを使用 | No | ないと関数の戻り値説明が出てこないだけ |
| @note | 関数の補足説明に使用することが出来る | No | 解放はAPI使用者がやることみたいなルールがかけます。関数系のオプションで一番効果があるのでは？ |
| @name | 変数や関数をグルーピングしたい時に使用 | No | 凄い好き |
ある程度記載が間違っていてもDoxygenがドキュメントを吐いてくれるので、まずは必須の@fileを先頭に記載しましょう。
こんな感じで。
/**
* @file state_machine.h
* @brief This is API for Sate machine
**/
#ifndef STATE_MACHINE_H_
#define STATE_MACHINE_H_
#include "state_manager.h"
注意点:先頭じゃないと意味がないです。最初ifndef の下に記載していたせいでハマりました。
Doxygenを使ってみよう
設定
- Doxywizardを起動します。
- ソースコードの指定を行います。最初の設定はまっさらなので、以下のような感じで指定していきます。
- ディレクトリは以下をまとめて対象に入れる場合は、Scan Recusivery にチェックを入れてください。
その他必要な設定を行います。困って調べて追加した設定を覚えている範囲で紹介。
プログラム言語, 出力HTMLフォーマットに関わる(?)設定
図の出力
static関数の表示
4. Runで出力。うまくいけば出力先のパスにファイルが出力されます。htmlの場合はindex.htmlを実行します。
出力結果
トップページはこんな感じに小ざっぱりしてます。デフォルトは左側のツリーすらなかったので困った。
例えばここからとある関数を開くと、引数の説明やreturn値の説明を見ることが出来ます。Graphvizの設定があると、この関数が使用する関数達までわかります。コメントが無くてもこの図は出てくると聞いたことがあるので、これだけでも有用なツールですね。
サンプル
今回利用したコードは以下となります。
https://github.com/developer-kikikaikai/design_pattern_for_c
Doxygenの出力コードは以下にコミットしてあるので、興味がある方はサンプルをご覧ください。
https://github.com/developer-kikikaikai/design_pattern_for_c_doc
Github連携
2018/05/22 追記
@tenmyoさんからのコメントを元に、githubとの連携を試してみました。
やりかたはこちらを参考にしました。
リポジトリの"Setting"⇒"GitHub Pages"のSourceにあるmaster branchを選択してしばらく待つだけ。
5分ほどでページが作成されます。与えられたTOPディレクトリが自分のリポジトリのTOPと連携しているので、
index.htmlを格納しているフォルダを指定することでページが公開されます。
こんな感じ。
コメントルール補足
便利だったもの: @name
一覧に記載した@nameが非常に便利でした。フォーマットはこんな感じ。@nameの後に記載した、@{から@}までの関数や変数をグルーピングしてくれます。
/*! @name XXXX */
/* @{ */
色々記載
/* @} */
**これらの関数やクラスが何のために定義されたものか？**が記載出来るので、大量にコメントを書かなくてもなんとなくやりたいことが見えやすくなります。
例えばこんな感じのコメント。用意した関数をどのように使いたいか等記載できます。
(private/publicは他言語なら言語で表現できるから、あまりいい例ではなかったかも)
/*! @name BuilderAction public method */
/* @{ */
/*! @brief construct action */
pthread_t builder_action_construct(builder_action_parameter_t * parameter);
/** @brief deconstruct action */
void builder_action_destruct(pthread_t tid);
/* @} */
...
/*! @name BuilderAction private method */
/* @{ */
/*! @brief run action */
static void * builder_action_run(void * this);
/* @} */
これのDoxygen側での見え方はこんな感じです。これだとstatic定義があるので明らかですが、関数の目的の違いがはっきりします。
これがXXXクラス用とか、XXX操作関連といったくくりでname決めしてあげるとさらによさそうですね。
公開ヘッダーじゃなくてローカルで閉じたAPI程度なら、最悪概要のコメントを忘れてしまった関数があったとしてもある程度どういうものかが察しやすくなるかなと。
困ったこと
/**, /*!で反応してコメントを出しているという点が、結構気付かないミスコメントに繋がっていました。
例えばこのような感じ。コードコメントを書く時にスペースや*の数を意識していなかったため、結構これでスルーされるものが多かったです。
こういうこともあるので、もう一から十までDoxygenに反応しなくても、ヘッダーだけちゃんとしてればよくない？とか思ってしまったり。
//*が一つなので反応しない
/* @brief XXXXXX */
//!を入れているけど、スペースが入ってしまい反応しない
/* ! @brief XXXXXX */
感想
Doxygen、ずっとがっつり使ってみたかったのですが、コーディングルール等があるので仕事では中々浸透しないんですよね。
でも今回の@nameのように、がっつりルールに縛らなくてもいいルールのコメントがあるなら、仕事での導入ハードルも下がるかもしれませんね。
例えばこんなルールとか。
- MUST: ファイル名の記載
- MUST: 公開ヘッダーについての必要なコメント。最低
@briefは入れる。 - SHOULD: 構造体や関数定義する場合は、出来るだけ
/*! @brief XXXXXX */でコメントを入れる。 - SHOULD: この構造体用の関数みたいな目的が一致するもの近くに定義し、以下で囲む。
/*! @name XXX */
/* @{ */
/* @} */
大分緩い条件だと思いますが、これくらいでも変数命名等に気を付けてあるコードなら、Graphvizパワーに頼れば十分人にも見やすくなるんじゃないかな？買いかぶりすぎかもですが。
参考
一番参考になりました。
最近覚えた便利アプリ[doxygen]
nameの参考
Doxygen公式 グループ化項 (latest release v1.5.9 - last update 14 Feb 2011とあるので注意)
変数の後ろにコメントを入れたい時の参考にしました。情報量が凄いです。
Ｃプログラマのためのdoxygen
github連携の参考
GitHub Pagesを使ってサクッとWebページを公開する