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というオープンソースソフトウェアを使用することで、上記コメントを元にしたプログラムのドキュメントを自動生成させます。
一旦実行してみる
以下のサイトより、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ステップで自動生成させることが出来ます。
- http://www.stack.nl/~dimitri/doxygen/download.htmlからdoxygen.exeを入手
-
“doxygen.exe -g”で、設定ファイル(Doxyfile)の雛形を作る
-
Doxyfileをエディタで開き、”INPUT =”の行に、ソースがある場所を指定する。
-
doxygen.exeを実行し、ドキュメントを自動生成させる
コメントを残す