VB.DOC メモ

ちょっと仕事でVisual Basic.NET で開発したプログラムのドキュメント化を行うことになりまして、VB.DOCを使うことになりました。

まぁ、色々とあったので、それらをメモしておきます。

使用したバージョンは、VB.DOC 0.4。
故あって、コマンドライン版。

VB.DOCは、VB.NETで書かれたソースから最終的なドキュメントを作成するツールではなく、中間ファイル的なXMLファイルを作成するだけ。
その中間ファイル的なXMLファイルから、人間が見やすい形式のドキュメントを作るのは NDOC（VB.DOCに付属）

MSDN風に出力使用とすると、HTML Help Workshopが必要（別途入手）。
JavaDoc風で出力するなら特に何も要らない。

ドキュメントを作成するには、ビルド済みのバイナリ（exeファイルやdllファイル）が必要。

サンプル等を見ると、コメントを「'''」で書いてあるが、デフォルト設定ではドキュメント化の対象となるコメントは「'」で始まるコメント。つまり全てのコメントが対象（逆に「'''」と書くと、''がドキュメントに出力される）。
設定の変更は可能。

日本語が遍く文字化けする。
ソースコードの文字コードを、UTF-8に変換すればOK。

コメント部分に <、& は使えない。
使いたい場合は、実体参照（&lt;、&amp; ）で記述する。

ドキュメントを改行することが出来ない。
HTMLの<p>に相当するタグ<para>はあるが、<br>に相当するタグが無い。
NDOCでは<br/>と書けば改行できるらしいが、VB.DOCの処理中に「不明なタグ」としてエラーになるので、結局NG。

エラー箇所の行番号が適当すぎる。

ドキュメント対象のプロジェクトの名前に非ASCII文字が含まれていると、例外を吐いて落ちる。
でも、ファイルは出来ているので無視したら良い（多分）。

namespaceに非ASCII文字が含まれていると（プロジェクト名が非ASCIIの場合も含む）、作成したドキュメントでリンクが切れている箇所がある。
リンク先のURL部分が「%8A%BF%8E%9A」という感じの指定になっているため。

インターフェースのメソッドのドキュメントは、メソッド宣言の後ろに書く。
（他のものは、定義の前に書く）

---

と、こんな感じなので、会社ではプリプロセッサとポストプロセッサを作って、色々とごまかしながら使っている。

今日の一冊
	トコトンやさしい暗号の本 作者: 伊豆 哲也 出版社/メーカー: 日刊工業新聞社 発売日: 2010/04 メディア: 単行本	一般の人向けの暗号の本で、 「広く浅く」 なら、今のところ、コレが一番