Doxygen記法でのコメント文

Doxygenに出力するものとしては、ファイルヘッダと関数ヘッダでしょうかね。

まずファイルヘッダ。

普段は、
・ファイル名
・ファイルの内容
・使い方
・更新履歴
・署名と作成日時

なんかを記入しています。

//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
// hogehoge.mel
//  サンプル
//
// usage:
//  コマンドラインへ hogehoge 入力して実行。
//==============================================================================
//  20??/??/?? : version.1.00
//      Relese.
//                                               made by Ishiko,since 20??/??/??
//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/

こんな感じ。
これをDoxygenコマンドで書き直すわけですが、

//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
//! @file hogehoge.mel
//! @brief Doxygen サンプル
//! @note コマンドラインに hogehoge で実行。
//! @par 変更履歴:
//!  - 20??/??/??: version.1.00
//!     - Relese.
//! @author Teruyuki Ishiko
//! @date since 20??/??/??
//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/

こんな風ですかね。
Doxygen で出力すると、


まぁ、これが自動で作成されるのであれば Doxygen コマンド書きますわ。
ここに付け加えるとしたら、参照の @sa かな？
Cの include みたいに source コマンドを解釈してくれるわけではないので、ココは自分で管理しないといけない。


続いて、関数ヘッダ。
proc の説明はだいたい、

global proc hogehoge()
/******************************************************************************
    main procedure.
 ******************************************************************************/
{
    print("\nhogehoge.\n");
    
}

みたいにしています。
 proc と {} の間にコメント書いているのは秀丸の部分編集するときに便利なのでこの順番。


こんな感じで、部分編集にしても関数ヘッダが編集できます。

で、Doxygen の場合も同じ感じで使いたいのですが、複数行コメントが上のままだと Doxygen で上手く解析してくれないようで注意が必要らしい。

回避策として、
/***************************************************************************//**

とすることで、Doxygen は行末の /** が Doxygen コマンドの開始と認識してくれて、MELでは行頭の /* がコメント開始、行末は//で単一行コメントとして無視しているという案配！？
なるほどです。


引数とか返り値用の Doxygen コマンドもあるようです。
その辺をふまえて・・・。

proc int _printHogehoge(
    string $str )                       //!< 表示する文字列
/***************************************************************************//**
    @brief @a $str を表示する。 __ERRORLEVEL__ を返す。
    @retval 0 成功
    @retval 1 失敗
 ******************************************************************************/
{
    print("\n"+$str+"\n");
    
    return 1;
    
}


global proc hogehoge()
/***************************************************************************//**
    @brief main procedure.
 ******************************************************************************/
{
    _printHogehoge("hogehoge");
    
}

これが Doxygen だとこうなります。


グローバルプロシージャとローカルプロシージャの区別はされないので、全部表示されているのがちょっと頂けないですが・・・。
なので、ローカルプロシージャにも関数ヘッダをいれないと、[Run doxygen]のときに警告が出たりします。

引数は @param
返り値は @retval のほかに @return って言うのもあるらしいですね。

詳しくは http://www.doxygen.jp/ で確認です。


markdown記法も軽く使えるようなので、地味に覚えないといけない事が多いなぁ。