C#でJavaDoc風のAPIリファレンスを作成する方法
C#でも、Javaで言うところのJavaDocみたいなコメントの書き方があります。
ドキュメントコメントと呼ばれていて、///で始まり、paramタグとかreturnsタグとかを書くことが出来ます。
このドキュメントコメントから、APIリファレンスを作成する方法を調べたので書いておくことにします。
今回、APIリファレンスを作成する対象は、Spracheというパーサージェネレーターです。
これはチュートリアルがあって結構わかりやすく書いてあるのですが、APIリファレンスが無いので使用する時に何を使えばいいのか困ります。
ソースを確認したところ、ドキュメントコメントは書いてあったので、APIリファレンスを作成して、ついでに手順をブログにまとめておこうという算段です。
まず、いつもの通りに先人の知恵を借りるということで、以下の2サイトを参考にさせてもらいました。
日本語対応はしていません。無くてもなんとかなったので。
2つ目のサイトを参考にしつつ、インストーラーに従って進めれば、つまずかずに出来ると思いますので、細かい点を補足します。
Sandcastle Help File Builderのインストール
GitHubへのプロジェクト移動について。紹介されているサイトに飛ぶとGitHubに移動したよというメッセージとURLがありますが、このページからダウンロードできる2015.1.12版でも目的は果たせました。
NuGetにも同名のパッケージがありますがインストールしても使い方がわかりませんでした。インストールしなくても問題なかったです。
ブラウザで見れれば良いので「HTML Help1」や「MS Help~」と書いてあるところは、そのままNextで進めました。それ以外は一応インストールしておこうという感じでやりました。
インストール後は、今回は既存のプロジェクトを使用するので、GitHubからSpracheをクローンしてプロジェクトの「プロパティ」を開いて「ビルド」メニューの「出力」にある「XML ドキュメント ファイル」のチェックをつけました。
Sandcastle Help File Builder GUIの操作
Windows上からSandcastle Help File Builder GUIを起動します。Launcherではないので注意してください。
「File」の「New Project」メニューから、shfbprojファイルを適当な場所に保存します。(shfbprojファイルがある場所に、APIリファレンスが作成されるようです。)
Documentation Sourcesは、いろいろ試しましたがcsprojファイルを指定すれば良いようです。なので、Sprache\src\Sprache\Sprache.csprojを指定します。
Buildメニューの「Build these help file formats:」で「Website(HTML/ASP.NET)」をチェックします。ブラウザで見るだけならこれで十分です。
Help Fileメニューの「Syntax filters」でC#をチェックします。
あとはサイトの通り、「Documentation」→「Build Project」と実行するとしばらく待った後に、shfbprojファイルがある場所にHelpディレクトリが作成されます。
ドキュメントコメントが不足している場合は、「missing~」という警告メッセージが赤字で表示されますが、必要なものは出力されています。
気になる場合は、Missing Tagsメニューのチェックボックスで出す/出さないを切り替えられます。
使用環境
Windows 8.1 64bit
Visual Studio 2013 Professional
Sandcastle Help File Builder Version:2015.1.12.0