Doxygenのコメントを限界まで減らそう
この記事は、C++ (fork) Advent Calendar 2013 17日目の記事になります。
なぜカレンダーを書くことにしたかと言うと、ちょうど空きがあって、よくみると同じ三人の並びが続いていたからこれは書けと言われていると幻聴が聞こえたと意味不明な供述しています。
多分もう書かないです。
先日の某勉強会の参加レポートでもいいんですが、２６日に書くネタが余ったのでそれについて書きます。。
（※先日の記事の補足ですが、Unicode識別子はMSVCとClangで実装済みです、日本語の識別子が使えるC++11は素晴らしいですね。ちなみにCは前世紀に制定されたC99の時点でUnicodeが規格に入っていたらしいです、gccでは未だに使えないので普及はしていません）
・自動ドキュメント作成ツール
Javaを使ってる人達はJavaDocなる標準的なツールを使って、コメントからドキュメントを自動生成するという文化を持っているそうです。そのため実装後に仕様書を作るのが非常に楽だと聞き及んでいます。
他にはC#ではsandcastleなんかのツールがあるそうです。
しかしながらC++においてはそういった標準ツール的な物が無く、ソースコードを読むとか、htmlでリファレンスを頑張って作るといった方法が行われています。
もちろん見栄えの良いリファレンスを作りたい場合は自動生成に頼れないのは仕方がありませんが、それ以外でサクッとそれなりの物を作りたい場合自動ドキュメント作成ツールは以下の理由で理にかなっています。
１．作るのが楽
関数が数百あって、クラスが数十あってと言ったソースから数百ページに及ぶリファレンスサイトを作るのはなかなか大変です。自動生成ツールなら”コメントを書くだけ”でいいので非常に楽ですね。
２．保守が楽
コードの変更が後から発生した場合でも、”コメントを変えるだけ”で良いので、リファレンスサイトを作る場合に比べて保守が楽です。
そんなこんなで、C++でドキュメントを自動生成したい場合はDoxygenが便利ですね。
・Doxygen
導入方法：
１．Doxygen公式から落とす
２．文字エンコーディングをいい感じに設定する。
３．ソースのあるフォルダを指定する
４．Run Doxygenする
５．リファレンスが出来たよ、やったー
それなりに有名なツールで解説サイトも結構あるので導入説明は省きます、こちらのサイトが詳しいです
http://alctail.sakura.ne.jp/tip/cplus_kannrenn/cplusplus/doc.shtml
・コメント書くのが面倒
というわけで自動生成させるべくコメントを書きましょう。
DoxygenはJavaDocスタイル、Qtスタイル、xmlスタイルの三種類のコメントに対応しているようです。
MSVCに合わせてxmlスタイルで書いてもかまいませんが、ブログで上手く表示されないのでJavaDocスタイルで書いてみましょう。ブログにプラグイン導入するのも面倒だから仕方ないですね。
まず、ファイルの説明を書いてみましょう。
各種Doxygen解説サイトにはこのような感じで書くようありましたが、面倒です改善しましょう。
はい、git等のまともなバージョン管理ツールを使っていればこのようなコメントは不要ですね。
説明などはクラスに付ければ良いでしょう。
次は関数にコメントを付けてみましょう。
引数が多いと結構な量のコメントが必要で面倒です。
アウトライン機能があるIDEの場合、勝手にアウトライン化されて鬱陶しいので出来ればコメントは１行以下にしておきたいです。また引数を変えるとコメントも直す必要があるのも面倒ですね。
はい、引数を日本語にすればコメント不要ですね。戻り値の説明は書かなくても分かるので不要ですね。
引数が変わってもコメントはそもそも無いので安心です。しかしながら上司が日本語引数を許可してくれないとかgcc使ってる場合は頑張って長いコメントを書くしか無いですね。
次はクラスの説明を書きましょう。
クラスの説明はわりと楽そうですが、サンプルコードを書きたい場合もあるでしょう。
サンプルコードを書いて実行したあとコピペして謎の*を１つずつ書く作業を繰り返すのはあきらかに面倒ですね。
はい、まずMovieSample.hにサンプルコード記述して、Doxygenの@includeを使って取り込めば楽ですね。
@includeを使う場合、Expert設定のInputのEXAMPLE_PATHを設定する必要があるのが面倒ですが、仕方ないですね。
最後にマニュアルのタイトルページを作ってみましょう。
※<を＜に置き換えています。
大体こんな感じでメインページと複数のサブページを記述できます。
ページ間のリンクも簡単に貼れるので、全般的な説明ページを作る事ができます。
ページはhtmlのタグが使えるので多少は見栄えも改善出来ます、改行は\nで行う事も出来ますよ。
しかしhtmlを使って書いていくのは面倒ですね。改行を書くのも面倒そうです。
・・・
はい、身内で使うドキュメントならメインページとか不要だし、Wordとかで作れば楽ですね。
・まとめ
他の解説サイトを見ると、Doxygenを使うために特殊なコードを書く必要があるかのような印象を受けるかと思います。しかし実際には。
@mainpage
@page
@ref
@include
の４つだけで十分なんですね。上の３つは作業の最後ぐらいにしか使わないし、サンプルコードを書かないなら@includeは要らないしで、実際かなり楽。自動生成のために特殊なコメントを書く必要無し、Doxygen便利やったー！
・・・
書き終わってふと思ったんですが、この記事C++殆ど関係ないですね。
おまけ：
以前に自分が作った仕様書です。殆ど手間無しでこれぐらいの物は作れると思います。
ダウンロード：仕様書
引数を日本語にしていない場合は、実際かなり面倒、自分だったら余裕で投げ出します(体験談)
なぜカレンダーを書くことにしたかと言うと、ちょうど空きがあって、よくみると同じ三人の並びが続いていたからこれは書けと言われていると幻聴が聞こえたと意味不明な供述しています。
多分もう書かないです。
先日の某勉強会の参加レポートでもいいんですが、２６日に書くネタが余ったのでそれについて書きます。。
（※先日の記事の補足ですが、Unicode識別子はMSVCとClangで実装済みです、日本語の識別子が使えるC++11は素晴らしいですね。ちなみにCは前世紀に制定されたC99の時点でUnicodeが規格に入っていたらしいです、gccでは未だに使えないので普及はしていません）
・自動ドキュメント作成ツール
Javaを使ってる人達はJavaDocなる標準的なツールを使って、コメントからドキュメントを自動生成するという文化を持っているそうです。そのため実装後に仕様書を作るのが非常に楽だと聞き及んでいます。
他にはC#ではsandcastleなんかのツールがあるそうです。
しかしながらC++においてはそういった標準ツール的な物が無く、ソースコードを読むとか、htmlでリファレンスを頑張って作るといった方法が行われています。
もちろん見栄えの良いリファレンスを作りたい場合は自動生成に頼れないのは仕方がありませんが、それ以外でサクッとそれなりの物を作りたい場合自動ドキュメント作成ツールは以下の理由で理にかなっています。
１．作るのが楽
関数が数百あって、クラスが数十あってと言ったソースから数百ページに及ぶリファレンスサイトを作るのはなかなか大変です。自動生成ツールなら”コメントを書くだけ”でいいので非常に楽ですね。
２．保守が楽
コードの変更が後から発生した場合でも、”コメントを変えるだけ”で良いので、リファレンスサイトを作る場合に比べて保守が楽です。
そんなこんなで、C++でドキュメントを自動生成したい場合はDoxygenが便利ですね。
・Doxygen
導入方法：
１．Doxygen公式から落とす
２．文字エンコーディングをいい感じに設定する。
３．ソースのあるフォルダを指定する
４．Run Doxygenする
５．リファレンスが出来たよ、やったー
それなりに有名なツールで解説サイトも結構あるので導入説明は省きます、こちらのサイトが詳しいです
http://alctail.sakura.ne.jp/tip/cplus_kannrenn/cplusplus/doc.shtml
・コメント書くのが面倒
というわけで自動生成させるべくコメントを書きましょう。
DoxygenはJavaDocスタイル、Qtスタイル、xmlスタイルの三種類のコメントに対応しているようです。
MSVCに合わせてxmlスタイルで書いてもかまいませんが、ブログで上手く表示されないのでJavaDocスタイルで書いてみましょう。ブログにプラグイン導入するのも面倒だから仕方ないですね。
まず、ファイルの説明を書いてみましょう。
/**
* @file Ragunaroku.cpp
* @brief 神々の黄昏ラグナロク。
* １面のボスの動きを実装しています。
*
* 残りのHPに応じ黄道１２星座をモチーフとした１２種類に行動パターンをとります。
* @par 最初はうんたらかんたらな行動
* @par どうのこうの
* @date 201X/XX/XX 新規作成
* @date 来月には完成させる
* @author オーディン
*/
各種Doxygen解説サイトにはこのような感じで書くようありましたが、面倒です改善しましょう。
はい、git等のまともなバージョン管理ツールを使っていればこのようなコメントは不要ですね。
説明などはクラスに付ければ良いでしょう。
次は関数にコメントを付けてみましょう。
/**
* 回転軸等を指定してImageを描画
* @param posX 描画座標X
* @param posY 描画座標Y
* @param axisX 回転軸X
* @param axisY 回転軸Y
* @param zoomRate 拡大率
* @param angle 回転角度
* @param isReverse 左右反転フラグ
bool DrawRotateAxis(int posX, int posY, int axisX, int axisY, double zoomRate, double angle, bool isReverse);
引数が多いと結構な量のコメントが必要で面倒です。
アウトライン機能があるIDEの場合、勝手にアウトライン化されて鬱陶しいので出来ればコメントは１行以下にしておきたいです。また引数を変えるとコメントも直す必要があるのも面倒ですね。
/** 回転軸等を指定してImageを描画 **/
bool DrawRotateAxis(int 描画座標X, int 描画座標Y, int 回転軸X, int 回転軸Y, double 拡大率, double 回転角度, bool 左右反転フラグ);
はい、引数を日本語にすればコメント不要ですね。戻り値の説明は書かなくても分かるので不要ですね。
引数が変わってもコメントはそもそも無いので安心です。しかしながら上司が日本語引数を許可してくれないとかgcc使ってる場合は頑張って長いコメントを書くしか無いですね。
次はクラスの説明を書きましょう。
/**
* 動画を管理し再生するクラス。
* @code
* bool MovieSample()
*{
* //何かのサンプルコード
*}
* @endcode
*/
class Movie
{
//何か実装コードが色々
}
クラスの説明はわりと楽そうですが、サンプルコードを書きたい場合もあるでしょう。
サンプルコードを書いて実行したあとコピペして謎の*を１つずつ書く作業を繰り返すのはあきらかに面倒ですね。
/**
* 動画を管理し再生するクラス。
* @include MovieSample.h
*/
class Movie
{
//何か実装コードが色々
}
はい、まずMovieSample.hにサンプルコード記述して、Doxygenの@includeを使って取り込めば楽ですね。
@includeを使う場合、Expert設定のInputのEXAMPLE_PATHを設定する必要があるのが面倒ですが、仕方ないですね。
最後にマニュアルのタイトルページを作ってみましょう。
/*!
@mainpage
＜B>イントロダクション＜/B>\n
@ref what \n
@ref howtoL \n
@ref licence \n
@ref qanda \n
\n
@ref classgroup\n
*/
/*!
@page qanda Ｑ＆Ａ
＜B>よくある質問＜/B>\n
準備中
*/
//他の@ref先も書く
※<を＜に置き換えています。
大体こんな感じでメインページと複数のサブページを記述できます。
ページ間のリンクも簡単に貼れるので、全般的な説明ページを作る事ができます。
ページはhtmlのタグが使えるので多少は見栄えも改善出来ます、改行は\nで行う事も出来ますよ。
しかしhtmlを使って書いていくのは面倒ですね。改行を書くのも面倒そうです。
・・・
はい、身内で使うドキュメントならメインページとか不要だし、Wordとかで作れば楽ですね。
・まとめ
他の解説サイトを見ると、Doxygenを使うために特殊なコードを書く必要があるかのような印象を受けるかと思います。しかし実際には。
@mainpage
@page
@ref
@include
の４つだけで十分なんですね。上の３つは作業の最後ぐらいにしか使わないし、サンプルコードを書かないなら@includeは要らないしで、実際かなり楽。自動生成のために特殊なコメントを書く必要無し、Doxygen便利やったー！
・・・
書き終わってふと思ったんですが、この記事C++殆ど関係ないですね。
おまけ：
以前に自分が作った仕様書です。殆ど手間無しでこれぐらいの物は作れると思います。
ダウンロード：仕様書
引数を日本語にしていない場合は、実際かなり面倒、自分だったら余裕で投げ出します(体験談)
スポンサーサイト
