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記法も軽く使えるようなので、地味に覚えないといけない事が多いなぁ。

DoxygenをつかってMELからドキュメントを抽出してみる

スクリプトの数が増えていくと、コメントなんかを読むためにファイルを開くのが面倒になります。
ソースコードからドキュメント作成できないかなぁと思っていたりしたのですが、まぁ、使うならDoxygenだろうと。

Doxygenの使い方を解説しているところは かなりありますが、MELに特化させている日本語サイトは見つからなかったので、備忘録。


まずはここから、
Doxygen の日本語サイト。
http://www.doxygen.jp/

Doxygen のインストーラへのリンクが分かりづらいので、ダウンロードサイトはこちら。

A binary distribution for Windows. All versions of Windows since XP are supported.
のところですね。
doxygen-x.x.xx-setup.exe をダウンロードします。
※以降 1.8.13を元に説明します。


無事インストールできたら、スタートメニューから Doxywizard を起動。

ＧＵＩが立ち上がるので、設定を始めます。
基本的な部分は他の言語と同じ感じで良いようです。

Step 1:の欄には Doxygen の bin フォルダでも指定しておきましょうか。

作業エリアとしてこのパスが使われるみたいです。


Wizard - Project
プロジェクト名とかは　とりあえず初期値のままでいくとして、ソースコードのパスと出力先を指定します。


自分の場合はSVNに登録してあるscriptsフォルダと出力先にdocというフォルダを作って指定しました。
サブフォルダが在る場合は、Scan recursively にチェック。

Wizard - mode


Documented entiries only にすることで Doxygen 用のコメントが記述されないと解析してくれませんが、ＭＥＬだとゴミが増えるだけみたいなのでこちらにします。
※Include cross-referenced ～ にチェックを入れるとhtmlにソースコードが含まれます。
Optimize は初期値のままC++で。


Wizard - Output


HTMLだけをチェックします。
with navigation panel を選ぶと、こんな感じにフレームが作成されて便利です。


With search function のチェックで検索機能が付きます。
スクリプトコマンドが増えたてきら便利でしょう。


Wizard - Diagrams
クラス図とか依存関係の表を作ってくれるみたいですが、MELには反応しないようなので
No Diagrams で問題ないです。



次に Expert タブ。
いろいろ変更する部分があります。

まずは、日本語が出力できるように文字コードとかを UTF-8 から Shift-jis へ変更。

Expert - Project
    DOXYFILE_ENCODING = CP932
    OUTPUT_LANGUAGE = Japanese


Expert - Input
    INPUT_ENCODING = CP932

の２箇所。
片方だけで良いような記事もありましたが、環境依存だったりするみたいで安全策として両方変えます。



今度は Doxygen に.melファイルを認識させます。

Expert - Input - FILE_PATTERNS
に *.mel を入力して＋で追加します。

Expert - Project - EXTENTION_MAPPING
では、mel=c と入力して＋で追加します。

こうすることで、.melファイルをc言語のルールを使って解析してくれます。


最後に Expert - Build
ここは特にイジる必要は無いようです。
初期状態では、Wizard - mode で設定したDocumented entiries onlyが効いて何も出力されないですが、EXTRACT_ALLにチェックを入れるとDoxygenの雰囲気が味わえます。

この部分の設定は日本語サイトのマニュアルから設定、Build 関係のオプションを熟読する必要がありそうですね。
初期値と違う部分が赤くなってくれるので便利です。


いよいよRunタブでhtmlに出力です。
doxygen用のコメントを書いてあるファイルであればＭＥＬでもこんな感じで出力されます。



書式に沿ったコメントを書く手間が必要ですが、なかなか良い感じ。



インストールせずに手っ取り早くdoxygenを知りたい人は、Ｃプログラマのためのdoxygen　が参考になるかと思います。

かなり綺麗にまとまっているのでオススメ。

ノードのアトリビュート名を調べる。

セッターやゲッター使うときにアトリビュートの名称を調べるのがなかなか大変。
使っていくうちに覚えたりはするのですが、しばらく経つと忘れたりするし、ロング名じゃなくてショート名が使いたかったりすることも有ります。

手っ取り早く調べるなら、スクリプトエディタの"Echo All Commands"にチェックを入れて、アトリビュートエディタを操作したログで確認するとか。
スライダー操作のものは分からなかったりしますけどね。

他にはシーンをASCIIで保存して、調べるとか。


どちらも面倒な事には違いがないので、調べるＭＥＬを組んでしまいます。

global proc tryGetAttrName(
    string $node,
    string $sea )
{
    string $attrs[] =`listAttr $node`;
    string $sAttrs[]=`listAttr -sn $node`;
    
    string $lowSea=tolower( $sea );
    string $lowAttr;
    print("\n--- "+$node+" ---------\n");
    int $i=0;
    for( $attr in $attrs )
    {
        $lowAttr=tolower( $attr );
        if( ""==$lowSea
         || `gmatch $lowAttr ("*"+$sea+"*")` )
        {
            print($attr+": "+$sAttrs[$i]+"\n");
            
        }
        
        $i++;
        
    }
    print("\n-----------------------\n");
    
}

ノード名とざっくりとしたアトリビュート名を渡せば、「ロング名」：「ショート名」がスクリプトエディタのログに表示されます。


たとえば

tryGetAttrName( "locator1","disp" );

とするとロングのアトリビュート名に"disp"が含まれるものが表示されます。


ほかには、

tryGetAttrName( "locator1","" );

みたいに調べたいアトリビュート名を""にすると全てのアトリビュート名が表示されます。

アウトライナーのノードに色を付ける

会社では最近までmaya2014を使用していたので気が付かなかったのですが、Attribute Editor の Display フレームに見慣れないアトリビュートが追加されていることに気が付きました。


Outliner Color で色を指定して、


Use Outliner Color のチェックを入れると・・・



Outliner 上のノードの色が変わります。
Shapeノードにも色が付けれるけれど、ふつう Outliner は Transformノードしか表示していないと思うので Shape の色を変えても、ほぼ意味なしですね。


Hidden In Outliner を使えばノード自体を消すこともできるみたいです。
Constrain とかを Outliner から消せるので便利かも。


Outliner の Display にも関連メニューが追加されていて、有効無効が切り替えられるようです。


ただ、この機能、アトリビュートエディタで編集すると maya の負荷によって色が変わったり変わらなかったりするみたいです。
設定しても、色が保存されなかったり。

なので、スクリプトで制御する方が安全。

設定するアトリビュートは、useOutlinerColor と outlinerColor ショートネームは uocol と oclr です。

global proc outlineColor()
{
    string $jnts[]=`ls -typ "joint"`;
    for( $jnt in $jnts )
    {
        setAttr ($jnt+".uocol") 1;
        setAttr ($jnt+".oclr") 0 1 1;
        
    }
    
    string $lcts[]=`ls -typ "locator"`;
    for( $lct in $lcts )
    {
        string $pLct[]=`listRelatives -p $lct`;
        setAttr ($pLct[0]+".uocol") 1;
        setAttr ($pLct[0]+".oclr") 1 1 0;
        
    }
    
}

transform ノードである joint は、リストして直接変えればよいですが、shape ノードである locator なんかは、親の transform を調べてソレを変更する必要があります。

Photoshopのjsxを更新するバッチ

Photoshopスクリプトを作成しているときバージョン管理を行いたい。
スクリプトを作る場合には当然欲しくなります。

でも Photoshopの Presets\Scripts を直接リポジトリに登録するとなると色々面倒。
とりあえず別のところをＳＶＮへコミットしておいてバッチファイルでコピーするのが妥当かな？


まずは、コピーするとき.jsxファイルがバラバラになっていると Presets\Scripts のなかもグチャグチャになるので、スクリプトごとにフォルダへまとめてソレをコピーする感じにしようと思います。
このことを前提にバッチを組んでいるので要注意。

で、バッチファイル。

@title %~nx0
@prompt %~n0$G

:: コピーするフォルダ名
set SCRIPT=hoge

:: Adobe フォルダがあるか調べる
@set ADOBE_PATH=%ProgramFiles%\Adobe\
@if not exist "%ADOBE_PATH%" goto :errAdobe

:: Photoshop フォルダを探す
@set SRC_FOLDER=%~dp0%SCRIPT%
@for /f "delims=*" %%F in ('dir /b "%ADOBE_PATH%" ^| find "Photoshop"') do call :copyAction "%%F"
@goto :endProcess



::------------------------------------------------------------------------------
:copyAction
    @set DST_FOLDER=%ADOBE_PATH%%~1\Presets\scripts\%SCRIPT%\
    @if not exist "%DST_FOLDER%" md "%DST_FOLDER%"
    
    xcopy "%SRC_FOLDER%" "%DST_FOLDER%" /s /y
    @exit /b



:errAdobe
    @echo Adobe のフォルダが見つかりません
    @goto :endProcess



:endProcess
    @pause

単にコピーするだけでは芸がないので、どんなバージョンのPhotoshopにも対応してみました。
ポイントは３箇所。

13行目でdelimsを設定しないとスペースで分割されてしまうのでダミーの文字を指定して分割されないようにしています。
同じく13行目、セット内でdirをfindへパイプするために ^| とエスケープさせています。
20行目callで渡された値はスペースで分割されないようダブルクォーテーション付きで渡されているので%~を使ってダブルクォーテーションを省いています。

たぶんコレでいけるはず。