次の方法で共有

  • [アーティクル]

基本的な本能

XML コメントを使用したコードのドキュメント化

Lisa Feigenbaum

この記事は、部分的に、Visual Studio のプレリリース版を基にしています。ここに記載されているすべての情報は、変更される場合があります。

目次

XML コメントの基礎
XML コメントのカスタマイズ
XML ドキュメント ファイルの生成
XML コメントを使用した Visual Studio の拡張
他の人のコードにコメントを追加するメリット
.NET Framework でのテクニック
より良いドキュメントの生成
Visual Studio 2010 の XML コメント

コードをドキュメント化する簡単かつ効率的な方法をお探しですか。それでしたら、XML コメントが最適なソリューションです。Visual Basic 用の XML コメントは Visual Studio 2005 で初めて導入されました。XML コメントを使用すると、プロジェクトのドキュメント ファイルを作成し、優れた開発環境を自分だけでなく、皆さんのコードを使用する同僚や他の人にも提供できます。

この記事では、XML コメントとその使用方法を紹介します。次に、XML コメントを使用して、コーディング環境をカスタマイズし、コード内のコメントからドキュメント ファイルを作成する方法について説明します。また、これまでよりも簡単にコード内で XML コメントを扱えるように、Visual Studio で今後装備される機能についてもいくつか紹介します。

XML コメントの基礎

XML コメントを使用すると、名前空間以外のほぼすべての定義をドキュメント化できます。これには、型 (クラス、モジュール、インターフェイス、構造、列挙、デリゲート)、フィールド (Dim)、プロパティ (Property)、イベント (Event)、およびメソッド (Sub、Function、Declare、Operator) が含まれます。

XML コメントは、ソース コードに直接、インラインで挿入されます。そのため、コードの進展に合わせて簡単に更新できます。XML コメントを挿入するには、次のように、定義のすぐ上に単一引用符を 3 つ ('") 入力します。

'''
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

または、定義行の先頭に「'"」と入力し、Enter キーを押します。Visual Studio によって、XML コメントを入力するためのスケルトンが挿入されます。

''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <remarks></remarks>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

この記事の目的に沿って、XML コメントの機能を示すために、1 つのパラメータに対して 1 つの単純な関数を使用しました。XML スケルトンは、定義によって異なります。たとえば、Function の XML スケルトンには returns 要素がありますが、Sub のスケルトンにはありません。メソッドの param タグの数もパラメータの数に応じて異なります。

Visual Studio では、定義に合った適切な XML スケルトンが挿入され、コメントの同期がとれなくなると警告が表示されますが、コメントが自動的に修正されることはありません。そのため、定義の変更に合わせて、コメントを更新する必要があります。

XML スケルトンが挿入されたら、Tabキーでコンテンツ ウェルを移動して、コメントを挿入できます。Visual Studio では、XML コメントとタグは色分けされます。また、必要ない要素 (remarks 要素など) を削除することができます。

さらに、元の XML スケルトンに含まれていない要素を追加することもできます。左山かっこ (&lt;) を入力すると、図 1に示すように、一般的なタグの一覧が IntelliSense のポップアップ メニューに表示されます。

図 1 IntelliSense の XML コメント

有効な XML であれば、XML コメントに追加できます。よく使用されるタグの一覧については、「ドキュメント コメントとして推奨される XML タグ (Visual Basic)」を参照してください。コメントが非常に大きな領域を占めている場合は、図 2 に示すように、コード エディタの左側にある +/- コントロールを使用してコメントを折りたたみ、summary だけが表示されるようにできます。

図 2 折りたたまれた XML コメント

XML コメントのカスタマイズ

前の例では、元の XML スケルトンにいくつか変更を加えました。エンタープライズ環境で働いている開発者は、社内の特定のガイドラインに合わせて、既定の XML コメントを変更しなければならない場合があります。このようなシナリオに対応するために、Visual Basic には、既定の XML スケルトンをカスタマイズする方法が用意されています。

まず、既定のコメント テンプレートを含む、VBXMLDoc.xml という名前の新しい XML ファイルを作成します。サンプルのファイルは、この記事のダウンロード コードに含まれています。使用している Windows と Visual Studio のバージョンに応じて、VBXMLDoc.xml を適切な場所に保存します (図 3を参照)。いずれの場合も、パスの &lt;ユーザー&gt; を実際のユーザー名に置き換えてください。

図 3 VBXMLDoc.xml の保存場所
Visual Studio 2005 Visual Studio 2008 Windows XP Windows Vista パス
X   X   C:\Documents and Settings\&lt;ユーザー&gt;\Application Data\Microsoft\Visual Studio\8.0
X     X C:\Users\&lt;ユーザー&gt;\AppData\Roaming\Microsoft\VisualStudio\8.0
  X X   C:\Documents and Settings\&lt;ユーザー&gt;\Application Data\Microsoft\Visual Studio\9.0
  X   X C:\Users\&lt;ユーザー&gt;\AppData\Roaming\Microsoft\VisualStudio\9.0

Visual Studio には、既定の XML スケルトンが組み込まれており、通常、それが挿入されます。しかし、起動時に VBXMLDoc.xml が存在する場合は、そのファイルの XML 定義が挿入されます。コード サンプルに含まれている VBXMLDoc.xml には、Visual Studio によって挿入される既定のタグが含まれています。既定値を変更するには、ファイル内で目的のコードの要素型を見つけ、XML 要素を変更します。

例として、Function に挿入される XML スケルトンを変更してみましょう。図 4 には、Function の既定のエントリとカスタマイズされたエントリが示されています。Template 要素の子は、XML コメントのスケルトンに挿入される XML 要素を表しています。CompletionList 要素の子は、Function の上に左山かっこ (&lt;) を入力したときに IntelliSense に表示される候補を表しています。

図 4 Function の XML タグ

既定の XML

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <remarks/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <remarks/>
    <returns/>
    <summary/>
  </CompletionList>
</CodeElement>

カスタマイズされた XML

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <author/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <permission cref=""/>
    <returns/>
    <summary/>
    <author/>
    <history/>
  </CompletionList>
</CodeElement>

図 4 の後半に示すように、簡単なカスタマイズをいくつか行いました。まず、既定のスケルトンと IntelliSense の両方から remarks 要素を削除しました。次に、既定のスケルトンと IntelliSense の両方に author 要素を追加し、さらに IntelliSense に history 要素を追加しました。

ここで、VBXMLDoc.xml の変更を有効にするために、Visual Studio をいったん閉じ、再び開く必要があります。再起動後は、次のように、Function の上に自動的に挿入される XML コメントに、remarks の代わりに author 要素が含まれるようになります。

''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <author></author>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

テンプレートに XML 要素を追加できますが、XML 値は追加できません。したがって、IDE で <author></author> を既定で挿入できますが、<author>Microsoft Corporation</author> を挿入することはできません。

XML ドキュメント ファイルの生成

Visual Basic コンパイラは、コード内で定義されたすべての XML コメントを使用して、アセンブリの XML ドキュメントを生成します。また、include 要素のファイル参照だけでなく、cref、permission、および name の各属性に使用される記号を解決します。

生成されたファイルでは、コメント化されたメンバは階層表示されません。代わりに、フラット リストとして表示されます。ファイルには各定義の一意の ID 文字列が含まれているため、それぞれのコメントをコード内の定義にマッピングできます (図 5 を参照)。この場合、ID 文字列は M:RegLib.Helpers.RegKeyExists(System.String) です。M はメソッドを意味し、RegLib.Helpers はパスを表しています。また、RegKeyExists はメソッド名、System.String はパラメータの型です。

図 5 生成された XML ドキュメントの抜粋

<?xml version="1.0" ?>
<doc>
<assembly>
<name>RegLib</name>
</assembly>
<members>
...
<member name="M:RegLib.Helpers.RegKeyExists(System.String)">
  <summary>Determines whether a specific registry key exists.</summary>
  <param name="regKey">Name or path of the registry key.</param>
  <returns>True if the registry key exists; otherwise, False.</returns>
  <author>Microsoft Corporation</author>
</member>
...
</members>
</doc>

XML ドキュメント ファイルを生成するには、コマンド ライン コンパイラか、Visual Studio インターフェイスのどちらかを使用します。コマンド ライン コンパイラでコンパイルする場合は、/doc オプションまたは /doc+ オプションを使用します。これによって、アセンブリと同じパスに同じ名前の XML ファイルが生成されます。別のファイル名を指定するには、/doc:<ファイル名> を使用します。

Visual Studio インターフェイスを使用する場合は、XML ドキュメント ファイルを生成するかどうかを制御する設定があります。その設定を行うには、ソリューション エクスプローラで [My Project] をダブルクリックして、プロジェクト デザイナを開きます。[コンパイル] タブに移動します。ウィンドウの下部にある [XML ドキュメント ファイルを生成する] を探し、オンになっていることを確認します。既定では、この設定はオンになっています。これによって、アセンブリと同じパスに同じ名前の XML ファイルが生成されます。

前の例では、クラス ライブラリ プロジェクトの名前が RegLib であるため、アセンブリと XML ドキュメント ファイルはそれぞれ RegLib.dll と RegLib.xml になります。ファイルが作成されるパスは、[ビルド出力パス] テキストボックスに表示されています。これらのファイルを生成するには、明示的なビルドが必要です。

マイクロソフトでは、すべての Microsoft .NET Framework アセンブリのドキュメントの生成に XML コメントを使用しています。XML ドキュメント ファイルはドキュメント化される DLL と同じ場所に配置され、同じ名前になります。

XML コメントを使用した Visual Studio の拡張

Visual Studio の機能の多くは、メンバをより簡単に使用できるようにするために、XML コメントを使用します。Visual Basic コンパイラは常にバックグランドで実行されているため、Visual Studio では、明示的なビルドなしで、XML コメントが作成された時点でそれを使用することができます。

XML コメントが最もよく使用される場所は、IntelliSense です。ヒントには、XML コメントの summary コンテンツが表示されます。メソッドが使用されると、IntelliSense によって、パラメータ ヘルプ ヒントと呼ばれる場所に param コンテンツが表示されます (図 6 を参照)。

fig06.gif

図 6 XML コメントを使用したパラメータ ヘルプ ヒント

XML コメントを使用することで、オブジェクト ブラウザでメンバを調べる作業は大幅に軽減されます。オブジェクト ブラウザには、summary、param、returns、remarks、typeparam、および exception の各コメントが存在する場合に、コメントが表示されます (図 7 を参照)。また、クラス デザイナ、クラス ビュー、およびオブジェクト テスト ベンチでも、XML コメントが利用可能な場合に、コメントが使用されます。

fig07.gif

図 7 XML コメントを使用したオブジェクト ブラウザ

他の人のコードにコメントを追加するメリット

先ほどは、XML コメントを定義に追加することで Visual Studio の関数の操作性をカスタマイズする方法を紹介しました。しかし、参照されるアセンブリで定義されているメンバの場合、必ずしもソースにアクセスできるわけではないため、同じプロセスに従うことは現実的ではありません。幸運なことに、参照されるメンバに使用できる別のプロセスがあります (この場合も XML コメントを使用します)。

ただし、1 つだけ重要な違いがあります。現在のソリューションのメンバの場合、Visual Studio の機能はソースに基づく XML コメントのメモリ内表現に対して動作します。この場合、XML ドキュメント ファイルは単なる出力であるため、生成しなくても、Visual Studio の機能は動作します。一方、参照されるアセンブリの場合、XML ドキュメント ファイルは入力として読み取られるため、コーディング環境内での動作に影響を与えます。

それでは例を見てみましょう。新しいプロジェクトを作成し、先ほど作成したアセンブリ (RegLib.dll) を参照します。生成された XML ドキュメント ファイル (RegLib.xml) はアセンブリと同じ場所に配置し、同じ名前を付ける必要があります。現在のプロジェクトから RegKeyExists メソッドにアクセスすると、そのメソッドが IntelliSense に表示されます。その際の表示方法を変更できます。

RegLib.xml を開き、summary コンテンツを "Determines whether the registry key exists" に変更します。更新は即座に行われるため、次回 IntelliSense のメンバにアクセスすると、ヒントに新しいテキストが表示されます (図 8 を参照)。

fig08.gif

図 8 IntelliSense のヒント

.NET Framework でのテクニック

プロジェクトから参照するアセンブリのもう 1 つの例として、.NET Framework があります。それでは、Microsoft.VisualBasic.dll について考えてみましょう。XML ドキュメント ファイルは、次の場所にあります。

C:\Windows\Microsoft.NET\Framework\v2.0.50727\en\Microsoft.VisualBasic.xml

その XML ファイルを開き、XML コメントを調べます。興味深い XML 要素がいくつかあることがわかります。たとえば、filterpriority には、Visual Basic の IntelliSense にメンバを表示する方法を指定します。値が 1 の場合は [よく使われる候補] タブに表示され、2 の場合は [すべての候補] タブに表示され、3 の場合は IntelliSense に完全に表示されなくなります。このメンバの filterpriority は 1 に設定されているため、[よく使われる候補] タブに表示されます。filterpriority の値を 2 に変更して、XML ファイルを保存すると、メンバは [すべての候補] タブに表示されるようになります。

.NET Framework の XML ドキュメント ファイルを編集する前に、コピーをあらかじめ作成してください。また、昇格された特権を持つアプリケーションでファイルを開く必要があります。Visual Studio ではファイル形式が維持されるため、Visual Studio を使用することをお勧めします。

このセクションで説明した方法を使用して、参照されるアセンブリのメンバに影響を与えることができます。ただし、その XML ドキュメント ファイルにアクセスできる場合に限ります。XML ドキュメント ファイルが存在しない場合は、作成できます。現在のアセンブリに定義されているメンバの filterpriority に影響を与えるには、System.ComponentModel.EditorBrowsable 属性を使用します。

他に興味深い要素としては、PermissionSet があります。この要素には、メンバがアクセス可能になる条件を指定します。この要素のコンテンツは、System.Security.Permissions.SecurityPermission 型を参照します。

それでは、現在のアクセス許可レベルを下げ、これが FileWidth へのアクセスにどのような影響を与えるかを見てみましょう。コンソールまたは Windows アプリケーションを作成します。ソリューション エクスプローラで [My Program] をクリックして、プロジェクト デザイナを開きます。[セキュリティ] タブをクリックし、[ClickOnce セキュリティ設定を有効にする] と [これは部分的に信頼するアプリケーションです] をオンにします。

この時点では、必要なアクセス許可が与えられていないため、FileWidth とそれに関連するメンバがグレー表示され、IntelliSense にアクセスできなくなります。この Visual Basic の機能は、"ゾーン内 IntelliSense" と呼ばれています。ヒントには、メンバを使用するために必要なアクセス許可の種類が表示されます。

PermissionSet 要素をメンバの XML ドキュメント ファイルに追加し、適切なアクセス許可を指定できます。

より良いドキュメントの生成

Visual Basic コンパイラによって生成された XML は判読できるものの、使い勝手が優れているわけではありません。移動性に優れた、見栄えの良いドキュメントを作成するために、さまざまなツールが作成されています。

まずは、マイクロソフトによって開発された、"Sandcastle" と呼ばれるツールを紹介します。Sandcastle をインストールしたら、ドキュメント化するアセンブリ、その依存関係、および XML ドキュメント ファイルを収集します。それらをすべて Sandcastle のインストール フォルダ (通常、C:\Program Files\Sandcastle\Examples\sandcastle) にコピーします。

昇格したコマンド プロンプトを開き、同じディレクトリに移動して、次のコマンドを実行します。

build_Sandcastle.bat prototype <your assembly name without the file extension>

この操作によって、ディレクトリとファイルが生成されます。.chm ディレクトリを開いて、その中にある .chm ファイルを開きます。図 9 に示すように、ヘルプのような形式で表示されます。

fig09.gif

図 9 Sandcastle を使用した .chm 出力

このツールでは、.chm 以外にもさまざまな形式で出力できます。Sandcastle の詳細およびニュースについては、blogs.msdn.com/sandcastle のブログを参照してください。

他には、NDoc というツールもよく使用されているので、検討してみてください。また、Visual Basic 9 の強力な XML 機能を使用して独自のカスタム ツールを作成することもできます。

Visual Studio 2010 の XML コメント

今後の展望としては、コード内の XML コメントの操作方法に新たな可能性がもたらされます。Visual Studio 2010 のエディタは Windows Presentation Foundation (WPF) を使用して書き換えられており、リッチな視覚化を実現できます。また、エディタの更新に伴い、新しいコンポーネント システムである Managed Extensibility Framework (MEF) に移行しました。そのため、Visual Studio でのアドインの登録が非常に簡単になりました。図 10 に、新しいエディタとコンポーネント モデルの上に構築された XML コメント ビューアの例を示します。

fig10.gif

図 10 Visual Studio 2010 の XML コメント ビューア

右上にあるボタンをクリックすることで、表示を WPF コントロールと元の XML の間で切り替えることができます。WPF コントロールでは、非常に見やすく表示されます。また、グラデーション化、角を丸めるなどの WPF 機能を利用できます。WPF を使用すると、画像やビデオを含めることもできます。これは、Visual Studio 2010 のリリースにおいて、サードパーティ製のアドインが利用する魅力的な機能の 1 つになるでしょう。

ご意見やご質問は instinct@microsoft.com まで英語でお送りください。

Lisa Feigenbaum は、マイクロソフトで Visual Basic コミュニティのプログラム マネージャを務めています。2004 年から、Visual Basic チームに加わりました。それ以前は、Visual Basic Editor および Debugger のプログラム マネージャとして、IntelliSense、エディット コンティニュ、コード スニペットなどの機能に取り組んでいました。彼女は、米国や海外のさまざまな会議やユーザー グループに出席したり、Channel 9 の Web キャストに出演したり、https://blogs.msdn.com/vbteam にある VB チームのブログに投稿したりしています。