株式会社ヘキサドライブ | HEXADRIVE

最近、めっきり視力が落ちて夕方にもなると視界がボケボケになって
加齢の衰えを感じずにはいられない今日この頃。ご無沙汰しておりますコンドウです。
ところでDoxygenってご存知でしょうか？ googleで検索すると何やら英語のサイトが
見つかりますね。google先生の自動翻訳で最初の出だし辺りを訳してみると

Doxygenは
ソースコードからドキュメントを生成
doxygenは、注釈付きのC + +ソースからドキュメントを生成するためのデファクトス
タンダードツールですが、それはまた、C、Objective-Cの、C＃、PHPは、JavaやPython、
IDL（CORBA、Microsoft、およびUNO / OpenOfficeのフレーバーなど、他の一般的な
プログラミング言語をサポートしています）、Fortranでは、VHDL、Tclで、そしてある
程度D.doxygenは、3つの方法であなたを助けることができます。

一部訳が変なところもありますが十分意図が伝わってきます。
そうです。doxygenとはソースコードからドキュメントを生成する為のとても便利な
ツールなのです
ただソースを解析してドキュメントを自動で出力できるほどインテリジェンスなもの
でも無い為、ある程度ソースにコメントを決められたルールの中で記述していく必要が
あります。ではどんな感じでコメントを記述すれば良いのか一例を紹介します。

/*!
@brief 画面に修飾された文字列を表示
予め設定されたフォントサイズ、フォント種類で画面の任意の位置に文字列を表示する。
@note この関数を実行する前に必ず、画面を初期化しておかなければならない。
@see getColor setColor
@param [in]     x      文字列の開始X座標
@param [in]     y      文字列の開始Y座標
@param [in]     mode   修飾するモード
@param [in]     ptr    文字列
@return 表示された文字数
@author Y.Kondo
@date 2013/06/21
*/
int dispStrings(int x, int y, int mode, const char *ptr);

コメント開始時の/*!や@で始まるキーワードがdoxygen用の単語となります。
@briefは概要を、@paramは引数を、@returnは戻り値の説明とそれぞれ意味が決まって
おります。
関数のプロトタイプ宣言の上に付けるとソースを修正する時でもコメントを修正しや
すくなりそうです。
他にも@file、@defgroup、@code等々、ドキュメントを見やすくする為の単語が沢山
存在しますがまずは基本的な物からスタートしていき生成されたドキュメント
(.html形式で出力される)を確認しながら、コメント記述に磨きをかけていければ
別途ドキュメントを作成する手間は大幅に半減できる非常に優れもののツールです。
doxygenの魅力を伝えるにはまだまだお伝えしたい事が沢山ありますが
「doxygen コメント 書き方」
等で検索していただくと先人たちの教えを戴けるかと思います。
もしソースのドキュメント管理に苦労している方ありましたら最初の内は覚える事で
苦労しますが必ず後に大きな助けになります