前回の記事で、C#のソースコードからドキュメントの自動生成が出来るようになりました。
今回は、ソース内のクラス階層や、関数の呼び出し関係を可視化する為にグラフ(画像)を表示できるようにします。

こんな感じで、どの関数が、どの関数をコールしているかを一目で分かるようにするのが目的です。

doxygenがグラフを生成する仕組み

doxygenは、自力でグラフ画像の生成することは出来ず、graphvizというソフトを利用しています。
graphvizは、AT&Tが開発したオープンソース(Common Public License ライセンス)のソフトウェアで、テキスト形式の設定ファイルより、以下のような画像を生成することが出来ます。

graphvizのセットアップを行う

まずは、準備としてgraphvizのセットアップを行い、単体で動作することを確認します。

下記のサイトへアクセスします。
http://www.graphviz.org/

画面左のdownloadをクリックします。

Executable Packageの下にある、リンクよりダウンロードを行います。

ダウンロードが出来たらセットアップを行います。
公式サイトからは、msiイメージのみがダウンロードできるので、通常だとインストールが必要です。

今回は、exeだけ入手できれば良いので、以下のコマンドでmsiパッケージからファイルの抽出を行います。
※下記の例では、c:\workにあるmsiファイルを、c:\work\extractに展開しています(途中で折り返していますが、実際は1行で記入します)

start /wait msiexec /a c:\work\graphviz-2.28.0.msi targetdir="c:\work\extract" /qn 
/li "c:\work\install.log"

インストーラからセットアップしたい場合は、ダウンロードしたgraphviz-x.xx.msiを実行します。
以下のようにインストール先を聞かれるだけなので、セットアップ自体は簡単です。

ファイルを展開したら、上記のファイル達を、doxygen.exeのあるフォルダにコピーしてしまいます。
(この作業は必須では有りませんが、1つのフォルダに纏めておくとUSBメモリなどで持ち運ぶ際に便利です)

無事graphvizがセットアップできたら、動作確認を行います。
エディタでテスト用のファイルを作成して…

graph graphname {
    a -- b -- c;
    b -- d;
}

  <p>bin\dot.exe -Tjpg test.txt -o test.jpg</p>

test.jpgが生成されていればOKです。

doxygenでgraphvizを使用する

次に、doxygenでgraphvizを使用できるようにします。graphviz用の設定は、Doxyfileを編集します。

HAVE_DOT               = NO
DOT_PATH               =
SOURCE_BROWSER         = NO
CALL_GRAPH             = NO
CALLER_GRAPH           = NO

HAVE_DOT               = YES
DOT_PATH               = .\graphviz\bin\
SOURCE_BROWSER         = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES

各パラメータの意味は以下のとおりです。

HAVE_DOT       : dot(graphvizに入っているコマンドdot.exe)を使用するか
DOT_PATH       : dot.exeのある場所
SOURCE_BROWSER : ドキュメントからソースへのリンクを付与するか
CALL_GRAPH     : 呼び出しグラフ(自分が誰をcallしているか)を表示するか
CALLER_GRAPH   : 呼び出されグラフ(誰から自分がcallしているか)を表示するか

上記の内、SOURCE_BROWSERはグラフ表示と直接関係ないのですが、SOURCE_BROWSERをYESにしておかないと画像が出力されないようなのでYESにしてます。

ここまで設定したら、再度doxygen.exeを実行します。

実行後、ドキュメントを確認すると…、なぜか画像が出来ていません

htmlフォルダの中を確認してみると、graph_legend.htmlというファイルが追加で作成されています。
graph_legendのファイルは、文字通りグラフの凡例なので、どうやらHAVE_DOTの定義自体は認識されているようです。

ここで、なぜ画像が生成されないのか、小一時間悩んだのですが…　どうやら今回対象としたMarkdownSharpは、クラス数･コードの構造がシンプルすぎで表示すべきグラフがまったく無かったという凡ミスでした。

ですので、今回は確認のために以下のパラメータを追加で変更しました。

EXTRACT_PRIVATE        = NO
　↓
EXTRACT_PRIVATE        = YES

EXTRACT_PRIVATEは、プライベートなメソッドの情報をドキュメント生成するかのフラグです。他から利用するライブラリ等のドキュメントを生成する場合は、privateなメソッド情報は不要なのでNOのままの方が分かりやすいのですが、ライブラリ自体の解析をしたい場合はYESしておくと便利なパラメータです。

改めて、doxygen.exeを実行します。なにやらグラフが生成されてそうなログが出力されました。

クラスのドキュメントを確認すると…、無事呼び出しグラフが出力されました!!
(画像が横長すぎて画面からはみ出てますが…この辺は次回調整します)

今回は以上です。
次回は、細かな見た目の改善を行います。

C#では、通常の”/* */”や “//”によるコメントに加えて、”///”で始まるコメントで、XML形式のドキュメントコメントを記述することが出来ます。

具体的な例としては、下記ソースのsummary,paramや、returns等が相当します。

//***************************************************************************
/// <summary> 指定されたファイルを読み込む
/// </summary>
/// <param name="fileName">ファイル名</param>
/// <returns>ファイルの内容</returns>
//***************************************************************************
private String GetText( String fileName ) {
    try {
        using ( StreamReader reader = new StreamReader( fileName, Encoding.GetEncoding( 932 ) ) ) {
            return reader.ReadToEnd();
        }
    } catch ( Exception ex ) {
        Console.WriteLine( ex.Message );
        return "";
    }
}

一旦実行してみる

以下のサイトより、doxygen本体をダウンロードします
2012/01時点での最新はver1.7.6でした。
http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc

ダウンロードしたzipを展開すると、doxygen.exeが入っています。
コマンドラインのプログラムなので、一旦実行してみるとエラーが出てしまいました。
(1行目の、”Doxyfile not found and no input file specified!”)
これは設定ファイルが無いためです。

設定ファイルが必要となるのですが、親切なことに雛形をdoxygen.exe自身で作成することが可能です。
先ほどのエラーメッセージを見るとdoxygen.exe -gで作成できるらしいのでその通りに実行します。
コマンド実行後、Doxyconfというファイルがある事を確認してください。

生成後、再度doxygen.exeを実行すると、なにやら処理が走りドキュメントの生成処理が行われます。

処理完了後、exeがあるフォルダを確認するとhtml/latexフォルダが出来ています。
latexというのは、unix系のOSで使用されれるドキュメント形式です。
今回はwindows環境で、html形式が参照できれば十分なので、htmlフォルダだけ確認します。

htmlフォルダの中には幾つかのファイルが出来ています。その中のindex.htmlを開くと、ドキュメントのトップページが表示されます。
今は、まだドキュメント生成を行う対象ファイルを指定していないため、当然ながら中身は空っぽです。

C#ソースのドキュメントを生成させてみる。

次にC#のソースコードよりドキュメントを自動生成させてみます。
自動生成させるプログラムは、前回触ってみたMarkdownSharpにします。

今回は説明のため、ソースをdoxygen.exeがあるフォルダにsrc\を作成し、その下に配置します。
(実際はどこに置いてあっても構いません)

srcフォルダの直下に*.csファイルが置いてあります。

ファイルを置いたら、ソースのありかをdoxygen.exeに伝える必要が有ります。
その方法ですが、先ほど生成した設定ファイル(Doxyfile)にフォルダを記載します。

ファイル内を見ると、以下のような記述があるので…

#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
 
# The INPUT tag can be used to specify the files and/or directories that contain
# documented source files. You may enter file names like "myfile.cpp" or
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
 
INPUT                  =

以下のように、src以下を見るように指示します。

INPUT                  = .\src

上記の変更を行ったら、再度doxygen.exeを実行します。
コマンドの出力内容を見ると、先ほど設置したソースを認識している事が分かります。

再度html\index.htmlファイルを開いています。
今度は、MainPageの横にNamespaces, Classesのリンクが出来ています。

Classesをクリックすると、クラス一覧が表示されます。
ここからドキュメントを確認したいクラスを選択します。

クラスをクリックすると、クラスが持っているメソッド(メンバ関数)や、プロパティなどが確認できます。
(今回はMarkdownSharp.Markdownを選択しました)

メソッドをクリックすると、各メソッドの詳細な説明が表示されます。

たったこれだけで、C#のソースからhtmlドキュメントを自動生成することが出来ました。

まとめ

C#のドキュメントは、以下の4ステップで自動生成させることが出来ます。

1. http://www.stack.nl/~dimitri/doxygen/download.htmlからdoxygen.exeを入手
   
2. “doxygen.exe -g”で、設定ファイル(Doxyfile)の雛形を作る
   
3. Doxyfileをエディタで開き、”INPUT =”の行に、ソースがある場所を指定する。
   
4. doxygen.exeを実行し、ドキュメントを自動生成させる
   

前回までの作業で、画面で入力したMarkdown形式テキストをその場でプレビュー可能となりました。
ただ、この方法だとテキストのサイズが小さいときは問題ないのですが、サイズが大きくなってくるとプレビューに時間が掛かるため、キー入力に対するレスポンス低下が起きてしまいます。

今回は、テキストが大量になっても入力のレスポンスが低下しないように改造してみます。

リアルタイムプレビュー時の負荷を下げる

レスポンス低下の問題ですが、原因は2つ存在します。

• 1文字でも変更があっると都度htmlへの変換を行う為、変換頻度が高すぎる。
• htmlへの変換処理をイベントハンドラ内で行っている為、変換中にキー入力が出来ない

ここでは、それぞれの問題に対して対応を考えます。

変換頻度が高すぎる件の改善

まず、前者の変換頻度が高すぎる件ですが、TextChangedのイベントハンドラ内で直接Markdown形式からhtmlへの変換を行うのを止めます。
以下の処理に変更することで、変換の頻度を落とします。

• テキストが変更されたタイミングでは、変更があった事を記録する(flgを立てる)だけにする
• 一定周期のタイマーで、flgが立っているかチェックする。
• flgが立っていれば変換を行う

それでは、実際に上記の改造を行ってみます。

前回までは、textBox1_TextChanged()で変換処理を直接行っていました。

private void textBox1_TextChanged( object sender, EventArgs e ) {
    // 変換ボタンが押されたことにする
    button1_Click( sender, e );
}

これを、flgを立てるよう変更します。

private bool changeFlg = false;
 
private void textBox1_TextChanged( object sender, EventArgs e ) {
    // 変換処理が必要なことを覚える
    changeFlg = true;
}

次に、タイマーコントロールをフォームに追加し、一定周期でイベントが走るようにします。(とりあえず1秒周期にしてみます)

private void timer1_Tick( object sender, EventArgs e ) {
    // 変換が不要な場合は何もしない。
    if ( !changeFlg ) {
        return;
    }
 
    // 変換処理を行う(変換ボタンを押したことにする)
    button1_Click( sender, e );
 
    changeFlg = false;
}

上記の改造後、再度プログラムを実行してみます。
改造の前に比べるとかなりレスポンスは向上しました(静止画では分かりませんが…)。


ただし、この状態でも、タイマーが走る1秒周期のタイミングで入力が引っかかる感じは残っています(テキストのサイズが大きい状態で編集を行うと顕著です)。

変換処理をイベント内で行っている件の改善

次は、Markdown形式の変換中にキー入力が出来ない為、引っかかりが残る件の対処です。

これは、タイマー処理のイベントハンドラがUIの入力イベントループの中で処理されていることが原因です(試しにタイマー処理内で、1秒程度スリープしてみると分かりやすいです)。

この問題に対してはC#(というか.Net Framework)の場合、BackgroundWorkerクラスを使用すると簡単に非同期処理を行うことが出来ます。

まずは、BackgroundWorkerコントロールを追加し、DoWork, RunWorkerCompletedイベントを追加します。
DoWorkイベントは、非同期で行うべき処理を記述します。イベント内では、GUIのコントロールに対して値をセットすることが出来ない点に注意が必要です。これは、スレッド間の競合が発生する恐れがある為です。実際に値をセットしようとすると、”実行時”に例外が発生します。

また、RunWorkerCompletedイベントの方は、DoWorkイベントが終了した際にコールされます。こちらは、GUI側のイベントループ内で走る処理ですので、画面コントロールに情報をセットすることが可能です。

ですので、BackgroundWorkerコントロールの基本的な流れは、DoWorkで時間の掛かる処理を行い、その後RunWorkerCompletedで処理結果を画面に反映するという流れになります。

で、具体的なプログラムの改造ですが、まずは、タイマーのイベントハンドラ処理を変更します。

private void timer1_Tick( object sender, EventArgs e ) {
    // 変換が不要な場合は何もしない。
    if ( !changeFlg ) {
        return;
    }
 
    // 変換処理を行う(変換ボタンを押したことにする)
    button1_Click( sender, e );
}

private void timer1_Tick( object sender, EventArgs e ) {
    // 変換が不要な場合は何もしない。
    if ( !changeFlg ) {
        return;
    }
 
    // すでに非同期処理中の場合は何もしない
    if ( backgroundWorker1.IsBusy ) {
        return;
    }
 
    // 変換処理を非同期で実施する
    backgroundWorker1.RunWorkerAsync( textBox1.Text );
}

backgroundWorker1のRunWorkerAsync()で、処理を非同期実行することが出来ます。
このメソッドを呼ぶと、別スレッドでbackgroundWorker1_DoWork()メソッドが実行されます。

また、RunWorkerAsyncメソッドに引数を渡すことで、DoWork()に対するパラメータを渡すことが可能です。引数は1つだけですがobject型なので、Dictionary<>やList<>をセットすれば、結果的に複数の情報を渡すことが可能です。今回必要な情報は1つだけなので、単純にstringの文字列を渡しています。

次に、実際に非同期処理を行うロジックをDoWork()に記述します。

private void backgroundWorker1_DoWork( object sender, DoWorkEventArgs e ) {
    //-------------------------
    // 入力パラメータを取得する
    //-------------------------
    string srcStr = e.Argument as string;
    if ( srcStr == null ) {
        srcStr = "";
    }
 
    //-------------------------
    // 変換処理を行う
    //-------------------------
    Markdown m = new Markdown();
    String destStr = m.Transform( srcStr ); 
 
    //-------------------------
    // 変換結果を返す
    //-------------------------
    e.Result = destStr;
}

先ほどRunWorkerAsync()で渡した情報は、DoWork()イベントの第二引数経由(e.Argument)で取得できます。e.Argumentは、当然ながらobject型なので、呼び元が渡したデータ型にキャストする必要があります。

キャストは、string srcStr =(string)e.Argument; といった形でも行うことが可能ですが、呼び元側で異なる型のオブジェクトを渡した場合、ここで例外が発生してしまいます。この為、”as”を使用したキャストを行います。asを使用した場合、元となるオブジェクトがキャストできない場合はnullが返る仕様なので、nullチェックを行ったうえで適切な処理を行います。

入力パラメータを取得したら、本来やりたかったMarkdownの変換を行った後、結果を返す必要があります。ここで、textBox2.Text = destStr;と書きたくなるところですが、前述したようにスレッド間の競合が発生する可能性があるので、この処理は認められません。

替わりに結果を、第二引数のResultプロパティ経由で渡します。こちらもArgumentと同様object型ですので、同様の配慮を行う必要があります。

最後は、変換結果を画面に反映させる処理です。
こちらは、BackgroundWorkerのRunWorkerCompleted()メソッドで行います。

private void backgroundWorker1_RunWorkerCompleted( object sender, RunWorkerCompletedEventArgs e ) {
    //--------------------------------------
    // textBoxに出力するために改行文字を変換
    //--------------------------------------
    String destStr = e.Result as String;
    if ( destStr == null ) {
        destStr = "";
    }
 
    String htmlText = GetHeader() + destStr.Replace( "\n", Environment.NewLine ) + GetFooter();
 
    //--------------------------------------
    // 変換結果をテキストで画面に表示
    //--------------------------------------
    textBox2.Text = htmlText;
 
    //--------------------------------------
    // 変換結果をブラウザにプレビュー
    //--------------------------------------
    webBrowser1.DocumentText =  htmlText;
}

DoWork()の時と同様、非同期処理の結果がe.Resultで取得できます。RunWorkerCompleted()はGUIのイベントループと同じスレッドで実行されるため、GUIコントロールにアクセスすることが可能です。

一方で、本メソッドで時間の掛かる処理を行うことは出来ません。ここで時間が掛かると、画面の応答速度が低下するため、操作性が悪くなってしまいます。

上記の改造を行ったうえで、再度プログラムを実行させると、無事、今まであった引っかかりがなくなりました。