もっと愛情を込メント
手始めに関数にコメントを付けてみます。CYYP_Class::CYYP_Class() { }
↑普通のコンストラクタです。 関数名の行にカーソルを置いてマクロを実行します。 行末にカーソルがあると行末コメントが入るので行の先頭、または途中に置いておきます。//******************************************************************************************** /** * @brief コンストラクタ. * @author Y.Yumemi * @date 2010/10/27(木) 15:53:08 */ //******************************************************************************************** CYYP_Class::CYYP_Class() { }
↑Doxygen書式に従って日付時間、自分の名前が入ります。 自分の名前は DoxyLabel.mac マクロファイルの$AuthorName = "Y.Yumemi";
に書いておきます。 @brief にコンストラクタと入っているのはこの関数がコンストラクタである事が判断できるからです。 デストラクタの場合も同様です。 関数を追加してみます。↓CYYP_Class::InitializeStep() { m_iStepState = 0; }
ステップ処理を初期化するといった内容の InitializeStep という関数を作りました。 同様に関数行でマクロを実行します。↓//******************************************************************************************** /** * @brief Stepの初期化. * @author Y.Yumemi * @date 2010/10/27(木) 15:55:53 * * @return なし (none) */ //******************************************************************************************** CYYP_Class::InitializeStep() { m_iStepState = 0; }
↑@brief に「Stepの初期化」と書かれました。 これは "INITIALIZE" という文字が「〜の初期化」である事を DoxyLabel.mac に記述してあるからです。if( $$fName == $$return ) call CreateNameByHead $$fName, $$FNAME, "INITIALIZE", "初期化";
追記して自分の書き方を覚えさせる事もオプション設定で自動的につけない事も出来ます。 普通は関数名の付け方等は大体決まっている物です。 特に追加せずデフォルトのままでも以下くらいの名前は自動的に付きます。↓//******************************************************************************************** /** * @brief ファイル名の取得. * @author Y.Yumemi * @date 2010/10/27(木) 16:24:56 * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool GetFileName(){}
//******************************************************************************************** /** * @brief テクスチャページの更新. * @author Y.Yumemi * @date 2010/10/27(木) 16:24:54 * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool UpdateTexturePage(){}
//******************************************************************************************** /** * @brief 選択したオブジェクトの破棄. * @author Y.Yumemi * @date 2010/10/27(木) 16:24:52 * * @return なし (none) */ //******************************************************************************************** void Destroy_SelectedObject(){}
基本クラスを継承した時などに会社を通してずっとお馴染みの関数などは改めて名前を付けなくても分かるだろう… イヤ、第３者が見ても分かるようにしておくのがコメントです。 クラスの宣言も作ります。*.h ファイルを作成です。class CYYP_Class { CYYP_Class(); ~CYYP_Class(){} InitializeStep(); };
↑クラスの先頭、つまり"class"の行でマクロを実行します。//******************************************************************************************** /** * @class CYYP_Class * @brief * @author Y.Yumemi * @date 2010/10/27(木) 16:31:45 */ //******************************************************************************************** class CYYP_Class { CYYP_Class(); ~CYYP_Class(){} InitializeStep(); };
↑クラスには @class が付加され、クラス名が入りました。 @brief は自動で付かないので自分で記入します。↓//******************************************************************************************** /** * @class CYYP_Class * @brief 私のクラス * @author Y.Yumemi * @date 2010/10/27(木) 16:31:45 */ //******************************************************************************************** class CYYP_Class { CYYP_Class(); ~CYYP_Class(); InitializeStep(); };
各メソッドにもコメントを付けましょう。 *.cpp にコメントが書いてあるのだからそっちを見てよ。 イヤイヤ、ヘッダーだけ見てもある程度分かる方がより良いです。 各メソッド単語の先頭でマクロを実行します。単行コメントは「単語の先頭で実行」です。↓//******************************************************************************************** /** * @class CYYP_Class * @brief 私のクラス * @author Y.Yumemi * @date 2010/10/27(木) 16:31:45 */ //******************************************************************************************** class CYYP_Class { /// コンストラクタ. CYYP_Class(); /// /*virtual*/ ~CYYP_Class(); /// Stepの初期化. InitializeStep(); };
↑それぞれのコメントが挿入されます。 ここでは 同名の *.cpp の関数コメントから解説を拾っています。 関数コメントを後で編集していても、その通りの解説文がここにも入ります。 デストラクタはまだ *.cpp に関数を作っていないので何も出ていないのです。 基本は *.cpp の方からコメントを付けますが、更新機能があるので先に付けても問題ないです。 コメントはソースに記述してある方を基準に考えられています。 これは単に製作者の経験から決められたルールです。 どんな拡張子をヘッダー、ソースと判断するかは DoxyLabel.mac に記述してあります。// 自動検索時の自身をヘッダーと判断する拡張子(小文字で指定) $HeaderExtList[0] = ".h"; $HeaderExtList[1] = ".inc"; // 自動検索時のソースファイル拡張子(小文字で指定) $SourceExtList[0] = ".cpp";
ソースは同フォルダから検索しますが DoxyLabel.mac にフォルダ構成を設定する事で別フォルダからも拾う事が出来ます。 またソースのコメントは DoxyLabel.mac でつけられたものである事が前提となります。 ここでデストラクタに "/*virtual*/" が付けられていますが、これはコーディング規約サポート機能です。 基本デストラクタに virtual を付けないのは継承を禁止しているか必要がない場合ですが 何もつけない時、忘れているのか意図して入れていないのか判断できないので 「意図して付けていないのならコメントとして入れて下さい」とルール付けされる場合のための機能です。 どんな文字を入れるかも指定できるので$CodingRule_DVC = "virtual ";
のようにしておけば自動で virtual を付ける機能になります。 デストラクタは関数の頭に追記されますが、基本は解説文に警告メッセージを付加する形でサポートしています。 他にも以下のサポート機能があります。 引数変数名の頭に'_'(アンダーバー)がついていない場合に説明部分に入れる警告文 コンストラクタにconstのついていないポインタ引数が指定された時に入れる警告文 引数変数名が１文字の時に入れる警告文 virtualのついていないデストラクタに自動検索で入れた時に出す 自動単行コメントはソース内を関数名で検索しているので該当するものが複数見つかった場合は全て列挙します。 クラス内のメソッドはクラス名を合わせて検索していますが "::"の前後に空間がある、ネームスペースやグローバルなどに同名の関数がある等すると正しく得られません。 具体例としてはコンストラクタにコメントを書かず、デストラクタにコメントを書いて、宣言のコンストラクタに単行コメントを実行すると クラス+コンストラクタで見つからず、フリー検索に移りデストラクタにヒットします。 この機能は「*.cppにコメントありき」である事を留意して下さい。 というわけでデストラクタも作ってコメントを書いてみます。↓//******************************************************************************************** /** * @brief デストラクタ. * @author Y.Yumemi * @date 2010/10/28(金) 14:36:29 */ //******************************************************************************************** CYYP_Class::~CYYP_Class() { }
InitializeStep() の @brief もデフォルトのままだとアルファベット混じりなので統一するためにカタカナに変えてみます。↓//******************************************************************************************** /** * @brief ステップの初期化. * @author Y.Yumemi * @date 2010/10/27(木) 15:55:53 * * @return なし (none) */ //******************************************************************************************** CYYP_Class::InitializeStep() { m_iStepState = 0; }
//******************************************************************************************** /** * @class CYYP_Class * @brief 私のクラス * @author Y.Yumemi * @date 2010/10/27(木) 16:31:45 */ //******************************************************************************************** class CYYP_Class { /// コンストラクタ. CYYP_Class(); /// /*virtual*/ ~CYYP_Class(); /// Stepの初期化. InitializeStep(); };
同じように関数名の先頭で実行します。/*virtual*/のついたデストラクタは注釈開始部分の '/'(スラッシュ)の上です。↓//******************************************************************************************** /** * @class CYYP_Class * @brief 私のクラス * @author Y.Yumemi * @date 2010/10/27(木) 16:31:45 */ //******************************************************************************************** class CYYP_Class { /// コンストラクタ. CYYP_Class(); /// デストラクタ. /*virtual*/ ~CYYP_Class(); /// ステップの初期化. InitializeStep(); };
↑上書き更新されました。 関数名の上行にそれと関係ない単行注釈を入れた場合は消されてしまいます。 オプション設定で旧コメントを消さないようにして消す必要がある場合は自分で消すか、 /** */ の複数行で注釈を書くようにして下さい。 ソース内のコメントを修正した時はヘッダーでもマクロを実行するだけで反映します。 むむ、たくさん触りすぎてどれが変わっているのか分からない？ 仕方がないので全部更新したいがクラスの注釈を１つずつ、ちまちま更新していくのは面倒だ！？ あまり関心できない話ですが…よくある事です。 そんな時はクラスを更新します。 class CYYP_Class の行で実行です。 分かりやすくするために一旦コメント文字のみ消して実行してみます。class CYYP_Class { /// CYYP_Class(); /// /*virtual*/ ~CYYP_Class(); /// InitializeStep(); };
↑class 行の上で実行です。//******************************************************************************************** /** * @class CYYP_Class * @brief * @author Y.Yumemi * @date 2010/10/28(金) 14:56:41 */ //******************************************************************************************** class CYYP_Class { /// コンストラクタ. CYYP_Class(); /// デストラクタ. /*virtual*/ ~CYYP_Class(); /// ステップの初期化. InitializeStep(); };
↑全ての関数に入りました。 デフォルトではコメント済みの物のみ更新しますがオプション設定で新規挿入するように事もできます。 昔のソースをDoxygen書式に変換する時などにも便利です。
製作・著作 YumemiYougie-Project