もっと愛情を込メント
単行コメントを付けてみます。int iLegth;
↑int の先頭で実行します。/// int iLegth;
↑"///" の後にカーソルが移動しているのでそのままコメントを記述します。/// 長さ. int iLegth;
単語の先頭という性質上 iLengthの先頭でも反応しますが基本は行の先頭文字で実行して下さい。 この単行注釈にも便利機能があります。 クラス定義のメンバ関数に対して単行コメントを打つ時に *.cpp から拾っていましたが関数呼び出し時も同様の機能があります。StartStep();
/// StartStep関数. StartStep();
クラス定義のメンバ関数の単行コメントと挙動は近いですがメカニズムは違うものなので、同ファイル内のみ有効で同名の関数などがあると全て拾います。 デフォルトでは更新(既に打たれているコメントを削除)も働きません。 これはソース内の単行コメントが必ずしも下行のコメントを指すとは限らないからです。 「単行は必ず、下行のコメントを指す。それ以外は範囲コメントを書く」と義務付けておけば更新を有効にして問題ありません。 その場合はオプション設定#DeleteOldLineFuncComm = 1; // 関数に単行コメントを入れる時、既存のコメントを残すか 0:残す 1:ヘッダー時のみ削除する 2:削除する
を 2 に変更して下さい。 行の末尾にコメントを入れてみます。int iTargetFileLegth;
↑';'の後ろ、リターンコードの上でマクロを実行します。int iTargetFileLegth; ///<
行末書式のコメントをが入ります。"///< "の後ろにカーソルが合わさっているのでそのままコメントを記述します。int iTargetFileLegth; ///< ファイルの長さ. int ii;
その下に宣言文を追加します。 それにも行末コメントを打ってみます。 "ii;"の後ろで実行です。int iTargetFileLegth; ///< ファイルの長さ. int ii; ///<
↑上のコメント位置に自動的に合わさりました。 上下に存在する近い方のコメントの位置に合わせているので場合によっては意図しないくらい後ろに付く事もあり得ますがその場合は後述の「揃え」を併用します。int iTargetFileLegth; ///< ファイルの長さ. int ii; ///< CYYPCLASS_MainFrame *pYypClassMainFrame;
更に下に宣言追加です。他の行より長いので後ろにずれてしまいました。↓int iTargetFileLegth; ///< ファイルの長さ. int ii; ///< CYYPCLASS_MainFrame *pYypClassMainFrame; ///<
そんな時はコメント揃え機能を使います。 ３行共範囲選択して実行です。int iTargetFileLegth; ///< ファイルの長さ. int ii; ///< CYYPCLASS_MainFrame *pYypClassMainFrame; ///<
↑選択範囲の行末コメントが揃いました。 揃える位置は「タブ１つ残して左に詰められるだけ詰めた位置に全てのコメントを合わせる」です。 オプション指定で一番右の物に合わせる事もできます。 任意の位置に合わせたい時は「右合わせにして、コメントを１つ合わせたい位置に移動させてから実行」です。 行末コメントにはもう１つあります。 行末更新コメントです。SampleFunction( 1, TRUE );
単語の途中にカーソルを合わせて実行です。 (=や+などがあると単語の途中とかの判定がややこしいので行末に移動してから左に１つ移動して実行がよいです)SampleFunction( 1, TRUE ); ///< Add. Y.Yumemi 2010/10/31
↑更新した人、日付が入ります。 ここでも"///< "の後ろにカーソルが合わさっているのでそのままコメントを記入します。 関数コメントの更新に記載するほどの修正でないものや 関数更新と併用してより詳細な変更点を明確にしたい時に利用します。SampleFunction( 1, TRUE ); ///< 第２引数をTRUEに変更 Add. Y.Yumemi 2010/10/31
"Add."の定型文もオプション設定で変更できます。 修正点を後でGrepする時の為にプロジェクトで定型文を決めておくとよいです。 デフォルトが"Add."なのは単に製作者が主に追加や挟み込み時に利用するからというだけです。 これまでのどれでもないコメントを打ってみます。bool CYYP_Class::StartStep( const int _iIndex, const int _iStep ) { }
↑{ } の間の何もない箇所で実行です。bool CYYP_Class::StartStep( const int _iIndex, const int _iStep ) { /** * @note Y.Yumemi * */ }
範囲コメントが入ります。 複数行に渡るコメントや、単行更新の対象としたくない場合に使用します。 Doxygenの @ に続く書式は DoxyLabelでサポートしているものが全てではなく、実際にはもっと多くの書式があります。 サポートしているものの方が極一部です。 それは製作者の「いかにDoxygenを通すか」ではなく「ソースコメントとして見た時にどうか」という点に重点を置いている事によります。 自由すぎるコメントに統一された規格を、というのが製作者がDoxygen書式を利用している最大の事由です。 結局はただのコメントなのでサポートされていない分については、後で好きに手を入れてくれればよいのです。 ただ、後から手を入れた場合は更新機能がサポートされなくなります。 それでも更新をかけた場合は、記載した物が消えてしまう事があるので、バックアップを忘れずに旧コメントは自動で消さないようにしておくのがお勧めです。 バックアップ管理は世代バックアップオープンが出来る オープンバックファイルマクロ「時の扉」 OpenBackFile.mac もお勧めです。 それでも以下の書式は更新に対応しています。//******************************************************************************************** /** * @brief ステップの開始. * * ここに関数の詳細な解説を * 記述できます * * @author Y.Yumemi * @note ここに複数行に渡るメモ書きを * 記述できます * @date 2010/10/31(月) 14:02:47 * * @exception 例外 * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * * @attention 注意事項 * @return bool TRUE:成 / FALSE:否 この関数はサンプルです。 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep ) {}
@note @exception @attention を追記。 末尾に補足説明を入れました。 更新してみます。//******************************************************************************************** /** * @brief ステップの開始. * * ここに関数の詳細な解説を * 記述できます * * @author Y.Yumemi * @note ここに複数行に渡るメモ書きを * 記述できます * @date 2010/10/31(月) 14:02:47 * * @exception 例外 * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * * @attention 注意事項 * @return bool TRUE:成 / FALSE:否 この関数はサンプルです。 */ //******************************************************************************************** //******************************************************************************************** /** * @brief ステップの開始. * * ここに関数の詳細な解説を * 記述できます * * @note ここに複数行に渡るメモ書きを * 記述できます * @attention 注意事項 * @exception 例外 * @author Y.Yumemi * @date 2010/10/31(月) 14:02:47 * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * * @return bool TRUE:成 / FALSE:否 この関数はサンプルです。 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep ) {}
@brief @note @attention @exception の順序が固定されています。 書く人によって好きな所に置いてほしくないので一定化してありますが、順序ついてはカスタマイズする事は難しくないと思います。 DoxyLabel.mac//■関数ラベル出力 call GetKeyString $lTopP+"@brief"; $output = $output + $in + $$return + $brief + "\n"; #ii=0;while( #ii<#briefSpace ){ #ii=#ii+1; $output = $output + $in + $lTopS+"\n";} // @breifの一部、セットで移動する call GetKeyString $lTopP+"@note"; if( $Note != "" ) $output = $output + $in + $$return + $Note + "\n"; call GetKeyString $lTopP+"@attention"; if( $Attention != "" ) $output = $output + $in + $$return + $Attention + "\n"; call GetKeyString $lTopP+"@exception"; if( $Exception != "" ) $output = $output + $in + $$return + $Exception + "\n"; call GetKeyString $lTopP+"@author"; if( $AuthorName != "" ) $output = $output + $in + $$return + $AuthorName + "\n";
の順番を入れ替える 末尾のコメントは互換用に入れてあるものです。製作者的には推奨していません。 @return の補足説明を複数行に渡って入れる事を認めているからなのですが//******************************************************************************************** /** * @brief ステップの開始. * @author Y.Yumemi * @date 2010/10/31(月) 14:02:47 * * @return bool TRUE:成 / FALSE:否 この関数はサンプルです。 */ //******************************************************************************************** bool CYYP_Class::StartStep() {}
↑この状態で引数を廃止、戻り値を void に変更して更新をかけると↓//******************************************************************************************** /** * @brief ステップの開始. * @author Y.Yumemi * @date 2010/10/31(月) 14:02:47 * * @return bool TRUE:成 / FALSE:否 この関数はサンプルです。 */ //******************************************************************************************** //******************************************************************************************** /** * @brief ステップの開始. * @author Y.Yumemi * @date 2010/10/31(月) 14:02:47 * * @return なし (none)TRUE:成 / FALSE:否 この関数はサンプルです。 */ //******************************************************************************************** void CYYP_Class::StartStep() {}
↑このように @return は「なし」に変わりますが続いて TRUE〜も残ってしまいます。 これは末尾のコメントとして残されている物です。 これは以下のオプション設定を 0 に変更する事で完全に入れ替える事が出来ます。// 戻り値なしのコメント更新時、定型分と異なるコメントを継承させる(0にしておくと必ず$Retnoneに置き換わるが末尾にreturnと繋がりのないコメントを記述していた場合、returnコメントの一部として一緒に消える) #RetSucVoidComment = 1; #RetSucVoidComment = 0;
にした時の実行結果//******************************************************************************************** /** * @brief ステップの開始. * @author Y.Yumemi * @date 2010/10/31(月) 14:02:47 * * @return bool TRUE:成 / FALSE:否 この関数はサンプルです。 */ //******************************************************************************************** //******************************************************************************************** /** * @brief ステップの開始. * @author Y.Yumemi * @date 2010/10/31(月) 14:02:47 * * @return なし (none) この関数はサンプルです。 */ //******************************************************************************************** void CYYP_Class::StartStep() {}
なぜデフォルトでこうなっていないかというと//******************************************************************************************** /** * @brief ステップの開始. * @author Y.Yumemi * @date 2010/10/31(月) 14:02:47 * * @return bool TRUE:成 / FALSE:否 この関数はサンプルです。 */ //******************************************************************************************** void CYYP_Class::StartStep() {}
↑のようになっている時に更新をかけると//******************************************************************************************** /** * @brief ステップの開始. * @author Y.Yumemi * @date 2010/10/31(月) 14:02:47 * * @return bool TRUE:成 / FALSE:否 この関数はサンプルです。 */ //******************************************************************************************** //******************************************************************************************** /** * @brief ステップの開始. * @author Y.Yumemi * @date 2010/10/31(月) 14:02:47 * * @return なし (none) */ //******************************************************************************************** void CYYP_Class::StartStep() {}
↑@return のコメントの一部として上書きされてしまうからです。 また @return の複数行解説に空行を入れたいなどの場合にも同じ問題が発生します。 デフォルトの設定としては既存のコメントが無くならない方を選択しています。利用者の書式に合わせて設定して下さい。 @retval は @return を複数行記述したものと同様に扱っています。 以下のように書式に関する設定もいくつかあります。// @briefの下に入れる空行の数(更新時は元のコメントの空行がそのまま継承されます) #BriefSpace = 0;
引数には特殊な書式があります。 未使用、可変個の引数 コメント文字は任意に変更できます。//******************************************************************************************** /** * @brief yyp_printf関数. * @author Y.Yumemi * @date 2010/10/31(月) 17:50:41 * * @param[in] int _iBate . * @param[in,out] int 未使用. * @param[in,out] char* _pFormat フォーム. * @param[in] 可変個の引数 * * @return なし (none) */ //******************************************************************************************** void yyp_printf( int _iBate, int /*予約*/, char *_pFormat, ... ) {}
関数ポインタ//******************************************************************************************** /** * @brief caller関数. * @author Y.Yumemi * @date 2010/11/01(火) 10:01:13 * * @param[in] void(int _a)* _new_functionName 名. * @param[in] int _p . * * @return なし (none) */ //******************************************************************************************** void caller( void (*_new_functionName)(int _a), int _p ) {}
省略可能な引数(インラインのみ) 省略可引数の場合、後に初期化値を変更して更新してもコメントは書き換えられませんのでご注意下さい。class CYYP_Class { //******************************************************************************************** /** * @brief 初期化. * @author Y.Yumemi * @date 2010/11/01(火) 10:00:51 * * @param[in] int _iParam (省略すると0). * * @return なし (none) */ //******************************************************************************************** void Init( int _iParam = 0 ) {} };
製作・著作 YumemiYougie-Project