もっと愛情を込メント
ファイルコメントを入れてみます。 ファイルの先頭で実行です。//******************************************************************************************** /** * @file test.cpp * @brief 要約説明 このファイルの詳細説明 * * @author Y.Yumemi * @date 2010/10/19(水) 14:32:56 */ //********************************************************************************************
ファイルコメントにも更新機能が働きます。 同様にファイル先頭で実行します。↓//******************************************************************************************** /** * @file test.cpp * @brief 要約説明 このファイルの詳細説明 * * @author Y.Yumemi * @date 2010/10/19(水) 14:32:56 * @date 2010/11/01(火) 10:38:32 Y.Yumemi 更新. */ //******************************************************************************************** //******************************************************************************************** /** * @file test.cpp * @brief 要約説明 このファイルの詳細説明 * * @author Y.Yumemi * @date 2010/10/19(水) 14:32:56 */ //********************************************************************************************
更新日と更新者が追加されます(ファイルコメントの場合は旧コメントが下になります)。 ファイル先頭には同作業者でも必ず@dateが追加されます(それ以外に更新をかける理由がないため)。 「ファイル内の関数などを更新した場合に、ファイル先頭にも同じように更新をつける」という使い方はあまりしません。 (膨大な量になる事と、バージョン管理履歴があれば必要ない物ですので) 主には共通定義などで大勢で修正する事が前提となるファイルで 各箇所に修正を入れてはかえって見難くなる場合にファイル先頭に集中させる目的で利用します。 ファイルコメントも末尾コメントが有効です。//******************************************************************************************** /** * @file test.cpp * @brief 要約説明 このファイルの詳細説明 * * @author Y.Yumemi * @date 2010/10/19(水) 14:32:56 * @date 2010/11/01(火) 10:52:28 Y.Yumemi 更新. 補足説明 */ //******************************************************************************************** //******************************************************************************************** /** * @file test.cpp * @brief 要約説明 このファイルの詳細説明 * * @author Y.Yumemi * @date 2010/10/19(水) 14:32:56 補足説明 */ //********************************************************************************************
Doxygenコメントの形式は JavaDoc と Qt スタイルがあります。 DoxyLabel では両方ともサポートしていますが、オプション設定によって指定されるので両方を混在させる事はできません。 JavaDoc モードの時は Qt のコメントが同じ DoxyLabel で書かれたものであっても更新、検索には反応しません。 完全無視ではなく、動作の保障対象外となります。 正しいコメントが挿入されません。 そういう時には DoxyChange.mac マクロが便利です。 このマクロは 通常コメントを Doxygenコメントに変換 JavaDoc <-> Qt を相互変換 してくれます。 通常コメントを Doxygen化する際には全角漢字が使われている注釈(""内の文字を除く)をコメントと判断しているので 意図しない文がコメント化されたり、コメントだけれどもアルファベットしか使っていないので判定されない といった場合もあります。 そう時はコメント対象から除いたり含めたりする設定文をオプション設定で登録して下さい。// コメント部分に以下の文字列が含まれていたらdoxy化対象から外す. (重複定義防止コメント等) $ExcludeList[ 0 ] = "重複定義防止"; // コメント部分に以下の文字列が含まれていたら強制的にコメントと見なす.(ExcludeListが優先) $ForceList[ 0 ] = "setters";
新規に入れる事がないのであれば#DoxyChange = true;
を false にしておけば既にDoxygenコメントとして入っている物だけが対象(Java<->Qt相互変換限定)となります。 変換後に単行が範囲になる事はありません。// // コメント //
↑というようなコメントは// /// コメント //
↑になります。 この DoxyChange.mac には先頭スペースをタブに変換(VisualStudioで作成したソース用)する機能もあります。 詳細は別途度金メントを参照して下さい。 また DoxyChange.mac は DoxyLabel.mac を呼び出し、行末注釈を空間ごとに揃えてくれます。 正しく更新が働かない状況は、スタイルだけでなくタブの数や上下の装飾設定の違うものも同様です。 設定としてカスタマイズできますが、主に現場の環境に合わせられるようにするための物ですので 新規利用をする場合はデフォルトの設定のまま利用する事をお勧めします。 異なった書式への対応は可能な限り行う予定ではありますが 基本は「書式は統一しましょう」のコンセプトのもとに作成されている物ですので、あまり自由なカスタマイズはお勧めできません。 それでも他の書式で書かれたソースを利用する事は多々ありますので#FreeComment = 0; // 1にすると当マクロ以外で挿入したコメントも更新の対象とする。書式により完全に継承できない場合があります
のオプション設定が用意されています。 どんな自由な書式にでも対応できるものではありませんので 既存のコメントを消すようにしていた場合、コメントでない部分まで消してしまう可能性があるのでご注意下さい。 自由と言ってもやはり Doxygen 書式である必要はあります。/* ----------------------------------------------------------------------------- */ /** @brief ステップ処理の開始. @author Y.Yumemi @date 2010/10/28(金) 15:32:22 @param const int _iIndex 管理番号. @param const int _iStep ステップ値. @param char* _pResPtr 内部で確保した情報構造体のポインタ. @return bool 成否 */ /* ----------------------------------------------------------------------------- */ bool CYYP_Class::StartStep( const int _iIndex, const int _iStep, char *_pResPtr ) { return TRUE; }
↑このコメントは 上下の注釈装飾が違う 行の頭がタブ DoxyLabelの原則であるparamのタブ区切りがされていない という違いがあるものです。 更新をかけてみます。↓/* ----------------------------------------------------------------------------- */ /** @brief ステップ処理の開始. @author Y.Yumemi @date 2010/10/28(金) 15:32:22 @param const int _iIndex 管理番号. @param const int _iStep ステップ値. @param char* _pResPtr 内部で確保した情報構造体のポインタ. @return bool 成否 */ /* ----------------------------------------------------------------------------- */ //******************************************************************************************** /** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/10/28(金) 15:32:22 * * @param const int _iIndex 管理番号. * @param const int _iStep ステップ値. * @param char* _pResPtr 内部で確保した情報構造体のポインタ. * * @return bool 成否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep, char *_pResPtr ) { return TRUE; }
コメント内容は拾われ、書式はマクロで設定している物に置き換わりました。 古いソース等を修正する場合は一度にまとめて更新する機会を設け、それ以外では #FreeComment は 1 にしないのが良いと思います。 関数行をサーチして一斉更新する機能を作成する予定はありません。 １つ１つ問題がない事を目で見て確認しながら変換して下さい。 次のような場合はどうでしょうか。 新しく配属された現場では DoxyLabelでコメントを書く事が義務付けられている。 書式はほとんど同じだ、しめしめ DoxyLabel でコメントがかけるぞ。 と思ったら少し違うぞ。/**************************************************************************************//** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/11/01(火) 18:30:03 * * @param[in] const int _iIndex 管理番号. * @param[in] const int _iStep ステップ値. * @param[in,out] char* _pResPtr 内部で確保した情報構造体のポインタ. * * @return bool TRUE:成 / FALSE:否 *//**************************************************************************************/ bool CYYP_Class::StartStep( const int _iIndex, const int _iStep, char *_pResPtr ) { return TRUE; }
↑上下の注釈装飾が一行にまとめられています。 これに更新をかけてみると…↓/**************************************************************************************//** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/11/01(火) 18:30:03 * * @param[in] const int _iIndex 管理番号. * @param[in] const int _iStep ステップ値. * @param[in,out] char* _pResPtr 内部で確保した情報構造体のポインタ. * * @return bool TRUE:成 / FALSE:否 *//**************************************************************************************/ //******************************************************************************************** /** * @brief StartStep関数. * @author Y.Yumemi * @date 2010/11/01(火) 18:52:11 * * @param[in] const int _iIndex 番号. * @param[in] const int _iStep . * @param[in,out] char* _pResPtr ポインタ. * * @return bool TRUE:成 / FALSE:否 */ //******************************************************************************************** bool CYYP_Class::StartStep( const int _iIndex, const int _iStep, char *_pResPtr ) { return TRUE; }
↑継承されませんでした。 新規にコメントを挿入したのと同じ物になっています。 これは旧コメントの判定を上下の注釈装飾で行っているためです。// 関数コメント等の上下を囲う装飾(改行必須、省略無効) $Decoration = "//********************************************************************************************\n"; //$DecorationD = "//********************************************************************************************\n"; // 下の装飾を上と分けたい時定義 #UseSubDecoration = 1; // 上下装飾に /*〜＊/を含める時、0にしておくと別途注釈で囲わない // プロジェクト全体の決まりでやむを得ず合わせなくてはならない場合の設定です. $DecorationD は定義せず、#UseSubDecoration = 1;を推奨します.
上記オプション設定を以下のように変更します。$Decoration = "/**************************************************************************************//**\n"; $DecorationD = " *//**************************************************************************************/\n"; // 下の装飾を上と分けたい時定義 #UseSubDecoration = 0; // 上下装飾に /*〜＊/を含める時、0にしておくと別途注釈で囲わない
/**************************************************************************************//** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/11/01(火) 18:30:03 * * @param[in] const int _iIndex 管理番号. * @param[in] const int _iStep ステップ値. * @param[in,out] char* _pResPtr 内部で確保した情報構造体のポインタ. * * @return bool TRUE:成 / FALSE:否 *//**************************************************************************************/ /**************************************************************************************//** * @brief ステップ処理の開始. * @author Y.Yumemi * @date 2010/11/01(火) 18:30:03 * * @param[in] const int _iIndex 管理番号. * @param[in] const int _iStep ステップ値. * @param[in,out] char* _pResPtr 内部で確保した情報構造体のポインタ. * * @return bool TRUE:成 / FALSE:否 *//**************************************************************************************/ bool CYYP_Class::StartStep( const int _iIndex, const int _iStep, char *_pResPtr ) { return TRUE; }
↑継承されました。 特に変更を加えていないので同じ内容です。 更に設定が相違する環境の場合。 同じPCで違うコーディング規約の仕事を複数請け負っている場合など 作業フォルダごとに設定を変えたい時は以下のようにする方法があります。 DoxyLabel.mac をコピーして名前を変更(DoxyLabelMyself.mac など)。 それぞれのマクロを設定を必要に応じて書き換え。 判定用の秀丸マクロを作成し、秀丸からはそのマクロを実行。マクロの中でファイルのパスから実行するマクロを選択させます。 マクロの例 DoxyLabelRoot.macif( (0 <= strstr( filename2, "tool" ) ) { // ファイルパスに"tool"が含まれる時. execmacro "DoxyLabelMyself.mac"; }else{ // それ以外, execmacro "DoxyLabel.mac"; }
DoxyLabelRoot.mac から環境に応じてそれぞれの設定のマクロが呼び出されます。 更に自動的に判定させる事ができないような場合、 前回のコメントを残す時、消す時 名前、日付を新しく入れない、従来のソースの整形用 を任意に使い分けたい時など 上記同様マクロを複数に分けてキー登録する事でも対応できますが ボタン別の設定を入れる事もできます。 F4、F4 + Shift に DoxyLabel.mac の実行を割り当てた場合。//********************************************************************************************************************** // マクロ実行時に押しているキーによって動作を変える設定. // サンプルを参考に設定したいキーの箇所で必要な定義、処理を追加して下さい // キー割り当てで利用するには以下のキーが押されている場合の実行マクロを全て この DoxyLabel.mac に設定して下さい //********************************************************************************************************************** if( iskeydown( 0x10 ) ) // Shift { // Shiftキーを押しながら実行すると名前、日付を入れない(元々書いてある関数の整形用). $AuthorName = ""; // 何も置かない場合は = "";とする $Date = "no"; // 自動の場合は = ""; 日付を置かない場合は = "no";とする }
もちろん iskeydown の部分にファイルパスを判定するようにして設定を分ける事も可能です。 変更する設定の規模に合わせてやりやすい方を選択すると良いでしょう。