秀丸のtagsファイルを使用して楽をする

自前のMELプロシージャが増えてくると、どんなプロシージャが有って、どんなツヅリだったかを思い出すのも苦労しはじめます。
そのためのDoxygenだったりするのですが、タイピングするのがなかなか面倒くさい。


秀丸の単語補完を使用するために、辞書ファイルへ追加していくなんて方法もありますが、スクリプトファイルやMELプロシージャを追加するたびに辞書ファイルをいじるのもなんか、そいつはちょっと科学的じゃない。

なので、tagsファイルを使って楽をしたいと思います。

手順としては、

1. ルールの作成
2. tagsファイルの作成
3. ダイレクトタグジャンプの指定
4. 単語補完の検索対象を追加

最初だけ４まで行わないといけませんが、一度設定してしまえば定期的に２を実行するだけで良くなります。


1.ルールの作成

まず、tagsファイルを作成するには、抜き出すためのルール（強調表示用の設定ファイル）が必要なので準備します。
秀丸でファイルを新規作成し、
その他(O) -> ファイルタイプ別の設定(C)...
で、
デザイン - 強調表示
を選びます。

おもむろに[全削除(R)]をおこない、
^global proc
を追加します。





そしたら[保存(V)...]で"melTags用"などとして.hilightファイルに保存します。


ここで注意。
.hilightファイルを保存したら、この設定は必要ないので、必ず[キャンセル]で閉じます。

[OK]をクリックしてしまうと全削除が確定されてしまい元に戻すのに手間取ります。


2.tagsファイルの作成

その他(O) -> tagsファイルの作成(G)...

を選びます。


各設定は以下。


対象ファイル(N):には[...]から絶対パスも指定可能です。
ルール(R):は、１で作成した.hilightファイルを指定し、出力ファイル名は"_melTags"とでもします。

対象ファイルが上図のように*.melのワイルドカードのみだと、現在開いているファイルのパスを基準に検索がかかります。
出力ファイルも同じように現在開いているファイルのパスへ出力されるので、実行する際は注意が必要です。

出力ファイルは、なにげに絶対パスでも指定できるのでmelのみで使うのなら絶対パスにするのも良いでしょう。


3.ダイレクトタグジャンプの指定

その他(O) -> 動作環境(E)...
その他コマンド - tagsファイル
から、tagsファイル(T):
に２で出力した"_melTags"を絶対パスで指定します。


上図は例によりＳＶＮに登録してあるフォルダですね。
ふつうならマイドキュ内のmaya\scriptsですかね。

ここもフルパスじゃないと開いているファイルのパスを基準にするので要注意。


4.単語補完の検索対象を追加

最後に、
その他(O) -> ファイルタイプ別の設定(C)...
その他 - 単語補完
から、単語補完の検索対象内[詳細(X)...]

で、追加の検索対象からtagsファイル(T)にチェックを入れます。


ココまで設定することで、単語補完にglobal procのプロシージャが指定できるようになります。




おまけ

tagsファイルを作成するときに、ファイル名をフルパスで出力(F) にチェックを入れたと思いますが、このおかげでダイレクトタグジャンプ([Ctrl]+[F10])が機能すると思います。

ダイレクトタグジャンプとは、なんぞや？みたいな感じだと思いますが、
たとえばgrepで検索をかけた結果から、ハイライトされている単語をダブルクリックすると該当箇所のファイルなんかが開いてくれますが、それと似たような事ができます。

単語補完でＭＥＬプロシージャを入力したら、プロシージャ名を選択して[Ctrl]+[F10]で.melファイルの該当箇所が開きます。
引数とか処理を確認するのに便利です。

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　が参考になるかと思います。

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