Doxygenで配列の役割を示す

MELの配列は参照渡しになっていますが、コメントに配列の役割を示しておいた方が何かと便利です。
自分の場合、接頭辞にCBR_(Call By Reference)を付けていたりして注意を促したりしていますが、Doxygenで出力する場合 @param に方向属性を付けることであらわすことが可能です。

基本通りに記述するなら、

proc _hogehoge0(
    string $CBR[],
    string $outList[],
    string $list[] )
/**************************************************************************//**
    @protected
    @brief test procedure.
    @param[in,out] $CBR 説明※参照渡し
    @param[out] $outList 説明※参照渡し、初期化あり
    @param[in] $list リスト
 ******************************************************************************/
{
    

これが、こんな感じになります。


param コマンドを書くのが面倒な場合は、

proc _hogehoge1(
    string $CBR[],                      //!< [in,out] 説明※参照渡し
    string $outList[],                  //!< [out] 説明※参照渡し、初期化あり
    string $list[] )                    //!< [in] リスト
/**************************************************************************//**
    @protected
    @brief test procedure.
 ******************************************************************************/
{
    

こんな風に引数の後ろへ記述する事も可能。
上のとほぼ同じように出力されます。


ただし下のように混在させると

proc _hogehoge2(
    string $test,                       //!< test comment.
    string $CBR[],
    string $outList[],
    string $list[] )
/**************************************************************************//**
 @protected
 @brief test procedure.
    @param[in,out] $CBR 説明※参照渡し
    @param[out] $outList 説明※参照渡し、初期化あり
    @param[in] $list リスト
 ******************************************************************************/
{
 

引数が複数に分割されてしまうので注意。


参照渡しは結構説明が長くなりがちなので、@pre や @post なんかも合わせると良いかも。

DoxygenのコメントデバッグTips4MEL

ローカルプロシージャにDoxygenコマンドの @private を付けると関数から見えなくする事が出来ます。
で、表示する時には Expert - Build の EXTRACT_PRIVATE にチェックを入れればよいということも。


けれども、ローカルプロシージャのコメントを修正した時、大量に並ぶ関数の中から修正した部分を選ぶのが大変になります。

これでは、修正したプロシージャを探すの大変です。

で、これを回避するTips。
編集しドキュメントを確認したいローカルプロシージャの @private を @protected というコマンドへ書き換えます。
Expert - Build の EXTRACT_PRIVATE はチェックを外します。
これでhtmlを出力。

@protected に変えたローカルプロシージャだけが表示されるようになりました。
編集を確認したら @private にしておくのを忘れずに。

ただし、EXTRACT_LOCAL_CLASSES のチェックが付いていること！
初期状態から変えなていなければ大丈夫です。