C#/VB.Netで開発をしていて、JavaDocいいな・・・なんてさみしい思いをしたことはないでしょうか。
実は、Sandcastleというツールを使用することで.NETでもソースコードからドキュメントを生成できます(こんな感じ)。今回はその方法をご紹介します。
Sandcastleのインストール
Sandcastleはもともとマイクロソフトが開発していたのですが、2010年ごろおやめになってしまい(ええっ!?)、それからしばらく.NETではJavaDocのようなツールがない状態でした。
その後(2012～2013年ごろ?) Eric Woodruffという心優しい方が元プロジェクトをforkし新たにSandcastle Help File Builderとして開発を行ってくださり、今に至ります。
前書きはこれくらいにして、ありがたくインストーラーを頂戴します。
https://github.com/EWSoftware/SHFB/releases
(※以前はCodePlexにありましたが、GitHubへ移行したようです)
インストーラーはちょっと珍しい形式で、必要なコンポーネントを順次インストールしていくスタイルです(左下のPrevious/Nextで進めていく)。
まずはヘルプファイルのビルドに必要なコンパイラをインストール。ここから落とせとリンクが指定されているので、仰せの通りにリンク先に遷移。
HTML Help Workshopを落とし、インストール。
後は必要ないので飛ばす。
続いて、Sandcastle本体をインストール。
完了したら、左下のNextを押して行って完了する。
Sandcastleを利用したドキュメントビルド
GUIを起動する。
ものすごい殺風景な画面が立ち上がるが、落ち付いて新規プロジェクトを作成する。
ドキュメント化したいクラスライブラリのdllを、Documentation Sourceとして追加する。
後はビルド設定。
作成したいファイル形式を選択。大抵Help1のみだが、Webサイトにしたい場合はWebsiteも選択。
タイトルなどその他もろもろを設定。PresentationStyleはもうvs2013も選べるみたい。
Summaryを設定することで、ヘルプファイル全体、また名称空間ごとの記述を設定することができる。
全ての設定が終わったら、Ctrl+Shift+BかBuild the help fileのボタンを押してドキュメントを作成する。
作成されたchmファイルはこんな感じになる。
コメントのタグはこちらになるが、普通にHTMLタグも使用可能(リンクとか)。
これでコメントを書くモチベーションががぜん上がる！に違いない。