ドキュメントコメント

ドキュメントコメントは、ソース内で特別に書式設定されたコメントであり、添付されているコードに関するドキュメントを生成するために分析できます。ドキュメントコメントの基本的な形式は XML です。ドキュメントコメントを含むコンパイルコードの場合、コンパイラは必要に応じて、ソース内のドキュメントコメントの合計を表す XML ファイルを出力できます。その後、この XML ファイルを他のツールで使用して、印刷またはオンラインドキュメントを作成できます。

この章では、ドキュメントコメントと、ドキュメントコメントで使用する推奨される XML タグについて説明します。

ドキュメントコメント形式

ドキュメントコメントは、 '''、3 つの単一引用符で始まる特別なコメントです。ドキュメント化する型 (クラス、デリゲート、インターフェイスなど) または型メンバー (フィールド、イベント、プロパティ、メソッドなど) の直前に配置する必要があります。部分メソッド宣言に関するドキュメントコメントは、本文を提供するメソッドのドキュメントコメントに置き換えられます (存在する場合)。隣接するすべてのドキュメントコメントが追加され、1 つのドキュメントコメントが生成されます。 '''文字の後に空白文字がある場合、その空白文字は連結に含まれません。例えば次が挙げられます。

''' <remarks>
''' Class <c>Point</c> models a point in a two-dimensional plane.
''' </remarks>
Public Class Point 
   ''' <remarks>
   ''' Method <c>Draw</c> renders the point.
   ''' </remarks>
   Sub Draw()
   End Sub
End Class

ドキュメントコメントは、 https://www.w3.org/TR/REC-xmlに従って整形式の XML である必要があります。 XML が整形式でない場合は、警告が生成され、エラーが発生したことを示すコメントがドキュメントファイルに含まれます。

開発者は独自のタグセットを自由に作成できますが、推奨セットは次のセクションで定義します。推奨されるタグの一部には特別な意味があります。

<param> タグは、パラメーターの記述に使用します。 <param> タグで指定されたパラメーターが存在し、型メンバーのすべてのパラメーターをドキュメントコメントで記述する必要があります。いずれかの条件が true でない場合、コンパイラは警告を発行します。
cref 属性は任意のタグにアタッチでき、コード要素への参照を提供します。コード要素が存在する必要があります。コンパイル時に、コンパイラは名前をメンバーを表す ID 文字列に置き換えます。コード要素が存在しない場合、コンパイラは警告を発行します。 cref属性で説明されている名前を探す場合、コンパイラは、含まれているソースファイル内に表示されるImportsステートメントを考慮します。
<summary> タグは、ドキュメントビューアで型またはメンバーに関する追加情報を表示するために使用することを目的としています。

ドキュメントファイルでは、型とメンバーに関する完全な情報は提供されず、ドキュメントコメントに含まれている情報のみが提供されることに注意してください。型またはメンバーに関する詳細情報を取得するには、ドキュメントファイルを実際の型またはメンバーのリフレクションと組み合わせて使用する必要があります。

推奨タグ

ドキュメントジェネレーターは、XML のルールに従って有効なタグをすべて受け入れて処理する必要があります。次のタグは、ユーザードキュメントでよく使用される機能を提供します。

<c> コードに似たフォントのテキストを設定します

<code> コードに似たフォントで 1 行以上のソースコードまたはプログラム出力を設定します

<example> 例を示します

<exception> メソッドがスローできる例外を識別します

<include> 外部 XML ドキュメントを含む

<list> リストまたはテーブルを作成します

<para> テキストに構造体を追加することを許可します

<param> メソッドまたはコンストラクターのパラメーターについて説明します

<paramref> 単語がパラメーター名であることを識別します

<permission> メンバーのセキュリティアクセシビリティを文書化する

<remarks> 型について説明します

<returns> メソッドの戻り値について説明します

<see> リンクを指定します

<seealso> [関連項目] エントリを生成します

<summary> 型のメンバーについて説明します

<typeparam> 型パラメーターについて説明します

<value> プロパティについて説明します

<c>

このタグは、説明内のテキストのフラグメントで、コードブロックに使用されるフォントを使用することを指定します。 (実際のコード行の場合は、 <code>を使用します)。

構文:

<c>text to be set like code</c>

例:

''' <remarks>
''' Class <c>Point</c> models a point in a two-dimensional plane.
''' </remarks>
Public Class Point 
End Class

<コード>

このタグは、1 行以上のソースコードまたはプログラム出力で固定幅フォントを使用することを指定します。 (小さなコードフラグメントの場合は、 <c>を使用します)。

構文:

<code>source code or program output</code>

例:

''' <summary>
''' This method changes the point's location by the given x- and 
''' y-offsets.
''' <example>
''' For example:
''' <code>
'''    Dim p As Point = New Point(3,5)
'''    p.Translate(-1,3)
''' </code>
''' results in <c>p</c>'s having the value (2,8).
''' </example>
''' </summary>
Public Sub Translate(x As Integer, y As Integer)
    Me.x += x
    Me.y += y
End Sub

<例>

このタグを使用すると、コメント内のコード例を使用して、要素の使用方法を示すことができます。通常、これにはタグ <code> の使用も含まれます。

構文:

<example>description</example>

例:

例については、「<code>」を参照してください。

<例外>

このタグは、メソッドがスローする例外を文書化する方法を提供します。

構文:

<exception cref="member">description</exception>

例:

Public Module DataBaseOperations
    ''' <exception cref="MasterFileFormatCorruptException"></exception>
    ''' <exception cref="MasterFileLockedOpenException"></exception>
    Public Sub ReadRecord(flag As Integer)
        If Flag = 1 Then
            Throw New MasterFileFormatCorruptException()
        ElseIf Flag = 2 Then
            Throw New MasterFileLockedOpenException()
        End If
        ' ...
    End Sub
End Module

<含める>

このタグは、外部の整形式 XML ドキュメントからの情報を含めるために使用されます。 XPath 式を XML ドキュメントに適用して、ドキュメントから含める XML を指定します。 <include> タグは、その後外部ドキュメントから選択された XML に置き換えられます。

構文:

<include file="filename" path="xpath">

例:

ソースコードに次のような宣言が含まれている場合:

''' <include file="docs.xml" path="extra/class[@name="IntList"]/*" />

外部ファイル docs.xml には次の内容が含まれています

<?xml version="1.0"?>
<extra>
    <class name="IntList">
        <summary>
            Contains a list of integers.
        </summary>
    </class>
    <class name="StringList">
        <summary>
            Contains a list of strings.
        </summary>
    </class>
</extra>

ソースコードに次の内容が含まれている場合と同じドキュメントが出力されます:

''' <summary>
''' Contains a list of integers.
''' </summary>

<リスト>

このタグは、項目のリストやテーブルを作成するために使用します。テーブルまたは定義リストの見出し行を定義するための <listheader> ブロックを含む場合があります。 (テーブルを定義する場合は、見出し内の用語のエントリのみを指定する必要があります)。

リストの各項目は、<item> ブロックで指定されます。定義リストを作成するときは、用語と説明の両方を指定する必要があります。ただし、テーブル、箇条書き、または番号付きリストの場合は、説明のみを指定する必要があります。

構文:

<list type="bullet" | "number" | "table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
    ...
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

例:

Public Class TestClass
    ''' <remarks>
    ''' Here is an example of a bulleted list:
    ''' <list type="bullet">
    '''     <item>
    '''        <description>Item 1.</description>
    '''     </item>
    '''     <item>
    '''         <description>Item 2.</description>
    '''     </item>
    ''' </list>
    ''' </remarks>
    Public Shared Sub Main()
    End Sub
End Class

<パラメータ>

このタグは、 <remarks> や <returns>などの他のタグ内で使用するために使用され、構造をテキストに追加できます。

構文:

<para>content</para>

例:

''' <summary>
''' This is the entry point of the Point class testing program.
''' <para>This program tests each method and operator, and
''' is intended to be run after any non-trvial maintenance has
''' been performed on the Point class.</para>
''' </summary>
Public Shared Sub Main()
End Sub

<パラメーター>

このタグは、メソッド、コンストラクター、またはインデックス付きプロパティのパラメーターを記述します。

構文:

<param name="name">description</param>

例:

''' <summary>
''' This method changes the point's location to the given
''' coordinates.
''' </summary>
''' <param name="x"><c>x</c> is the new x-coordinate.</param>
''' <param name="y"><c>y</c> is the new y-coordinate.</param>
Public Sub Move(x As Integer, y As Integer)
    Me.x = x
    Me.y = y
End Sub

<paramref>

このタグは、単語がパラメーターであることを示します。ドキュメントファイルを処理することで、いくつかの独自の方法でこのパラメーターの書式設定を行うことができます。

構文:

<paramref name="name"/>

例:

''' <summary>
''' This constructor initializes the new Point to
''' (<paramref name="x"/>,<paramref name="y"/>).
''' </summary>
''' <param name="x"><c>x</c> is the new Point's x-coordinate.</param>
''' <param name="y"><c>y</c> is the new Point's y-coordinate.</param>
Public Sub New(x As Integer, y As Integer)
    Me.x = x
    Me.y = y
End Sub

<許可>

このタグは、メンバーのセキュリティアクセシビリティを文書化します

構文:

<permission cref="member">description</permission>

例:

''' <permission cref="System.Security.PermissionSet">Everyone can
''' access this method.</permission>
Public Shared Sub Test()
End Sub

<注釈>

このタグは、型に関する概要情報を指定します。 ( <summary> を使用して、型のメンバーを記述します)。

構文:

<remarks>description</remarks>

例:

''' <remarks>
''' Class <c>Point</c> models a point in a two-dimensional plane.
''' </remarks>
Public Class Point 
End Class

<戻り>

このタグは、メソッドの戻り値を記述します。

構文:

<returns>description</returns>

例:

''' <summary>
''' Report a point's location as a string.
''' </summary>
''' <returns>
''' A string representing a point's location, in the form (x,y), without
''' any leading, training, or embedded whitespace.
''' </returns>
Public Overrides Function ToString() As String
    Return "(" & x & "," & y & ")"
End Sub

<見る>

このタグは、テキスト内でリンクを指定することを許可します。 ( <seealso> を使用して、[関連項目] セクションに表示されるテキストを指定します)。

構文:

<see cref="member"/>

例:

''' <summary>
''' This method changes the point's location to the given
''' coordinates.
''' </summary>
''' <see cref="Translate"/>
Public Sub Move(x As Integer, y As Integer)
    Me.x = x
    Me.y = y
End Sub

''' <summary>
''' This method changes the point's location by the given x- and
''' y-offsets.
''' </summary>
''' <see cref="Move"/>
Public Sub Translate(x As Integer, y As Integer)
    Me.x += x
    Me.y += y
End Sub

<関連項目>

このタグは、「関連項目」セクションの項目を生成します。 ( <see> を使用して、テキスト内からリンクを指定します)。

構文:

<seealso cref="member"/>

例:

''' <summary>
''' This method determines whether two Points have the same location.
''' </summary>
''' <seealso cref="operator=="/>
''' <seealso cref="operator!="/>
Public Overrides Function Equals(o As Object) As Boolean
    ' ...
End Function

<概要>

このタグは、型メンバーを表します。 ( <remarks> を使用して型自体を記述します)。

構文:

<summary>description</summary>

例:

''' <summary>
''' This constructor initializes the new Point to (0,0).
''' </summary>
Public Sub New()
    Me.New(0,0)
End Sub

<typeparam>

このタグでは、型パラメーターについて説明します。

構文:

<typeparam name="name">description</typeparam>

例:

''' <typeparam name="T">
''' The base item type. Must implement IComparable.
''' </typeparam>
Public Class ItemManager(Of T As IComparable)
End Class

<価値>

このタグは、プロパティを記述します。

構文:

<value>property description</value>

例:

''' <value>
''' Property <c>X</c> represents the point's x-coordinate.
''' </value>
Public Property X() As Integer
    Get
        Return _x
    End Get
    Set (Value As Integer)
        _x = Value
    End Set
End Property

ID 文字列

ドキュメントファイルを生成するときに、コンパイラは、一意に識別するドキュメントコメントでタグ付けされたソースコード内の各要素の ID 文字列を生成します。この ID 文字列は、外部ツールで使用して、コンパイル済みアセンブリ内のどの要素がドキュメントコメントに対応するかを識別できます。

ID 文字列は次のように生成されます。

文字列に空白は配置されません。

文字列の最初の部分は、単一の文字とそれに続くコロンによって、文書化されているメンバーの種類を識別します。イベント (E)、フィールド (F)、コンストラクターと演算子 (M)、名前空間 (N)、プロパティ (P)、型 (T) を含むメソッドなど、次の種類のメンバーが定義されます。感嘆符 (!) は、ID 文字列の生成中にエラーが発生したことを示し、残りの文字列はエラーに関する情報を提供します。

文字列の 2 番目の部分は、グローバル名前空間から始まる要素の完全修飾名です。要素の名前、その外側の型、および名前空間はピリオドで区切られます。項目自体の名前にピリオドがある場合は、シャープ記号 (#)に置き換えられます。 (この名前にこの文字を持つ要素はないと想定されます)。型パラメーターを持つ型の名前は、バッククォート (') で終わり、その後に型の型パラメーターの数を表す数値が続きます。入れ子になった型は、それらを含む型の型パラメーターにアクセスできるため、入れ子になった型には暗黙的に含まれる型の型パラメーターが含まれており、この場合、それらの型は型パラメーターの合計でカウントされます。

引数を持つメソッドとプロパティの場合は、括弧で囲まれた引数リストが続きます。引数がない場合は、括弧は省略されます。引数はコンマで区切られます。各引数のエンコードは、CLI シグネチャと同じです。引数は完全修飾名で表されます。たとえば、 Integer が System.Int32になったり、 String が System.Stringになったり、 Object が System.Objectになったりします。 ByRef修飾子を持つ引数には、型名の後に '@' があります。 ByVal、Optional、またはParamArray修飾子を持つ引数には、特別な表記はありません。配列である引数は、コンマの数がランク 1 である [lowerbound:size, ..., lowerbound:size] として表され、各次元の下限とサイズ (既知の場合) は 10 進数で表されます。下限またはサイズの指定がない場合は省略されます。特定のディメンションの下限とサイズを省略すると、':' も省略されます。配列の配列は、レベルごとに 1 つの "[]" で表されます。

ID 文字列の例

次の例は、VB コードのフラグメントと、ドキュメントコメントを持つことが可能な各ソース要素から生成された ID 文字列を示しています。

型は、完全修飾名を使用して表されます。

Enum Color
    Red
    Blue
    Green
End Enum

Namespace Acme
    Interface IProcess
    End Interface

    Structure ValueType
        ...
    End Structure

    Class Widget
        Public Class NestedClass
        End Class

        Public Interface IMenuItem
        End Interface

        Public Delegate Sub Del(i As Integer)

        Public Enum Direction
            North
            South
            East
            West
        End Enum
    End Class
End Namespace

"T:Color"
"T:Acme.IProcess"
"T:Acme.ValueType"
"T:Acme.Widget"
"T:Acme.Widget.NestedClass"
"T:Acme.Widget.IMenuItem"
"T:Acme.Widget.Del"
"T:Acme.Widget.Direction"

フィールドは、完全修飾名で表されます。

Namespace Acme
    Structure ValueType
        Private total As Integer
    End Structure

    Class Widget
        Public Class NestedClass
            Private value As Integer
        End Class

        Private message As String
        Private Shared defaultColor As Color
        Private Const PI As Double = 3.14159
        Protected ReadOnly monthlyAverage As Double
        Private array1() As Long
        Private array2(,) As Widget
    End Class
End Namespace

"F:Acme.ValueType.total"
"F:Acme.Widget.NestedClass.value"
"F:Acme.Widget.message"
"F:Acme.Widget.defaultColor"
"F:Acme.Widget.PI"
"F:Acme.Widget.monthlyAverage"
"F:Acme.Widget.array1"
"F:Acme.Widget.array2"

コンストラクター。

Namespace Acme
    Class Widget
        Shared Sub New()
        End Sub

        Public Sub New()
        End Sub

        Public Sub New(s As String)
        End Sub
    End Class
End Namespace

"M:Acme.Widget.#cctor"
"M:Acme.Widget.#ctor"
"M:Acme.Widget.#ctor(System.String)"

メソッド。

Namespace Acme
    Structure ValueType
        Public Sub M(i As Integer)
        End Sub
    End Structure

    Class Widget
        Public Class NestedClass
            Public Sub M(i As Integer)
            End Sub
        End Class

        Public Shared Sub M0()
        End Sub

        Public Sub M1(c As Char, ByRef f As Float, _
            ByRef v As ValueType)
        End Sub

        Public Sub M2(x1() As Short, x2(,) As Integer, _
            x3()() As Long)
        End Sub

        Public Sub M3(x3()() As Long, x4()(,,) As Widget)
        End Sub

        Public Sub M4(Optional i As Integer = 1)

        Public Sub M5(ParamArray args() As Object)
        End Sub
    End Class
End Namespace

"M:Acme.ValueType.M(System.Int32)"
"M:Acme.Widget.NestedClass.M(System.Int32)"
"M:Acme.Widget.M0"
"M:Acme.Widget.M1(System.Char,System.Single@,Acme.ValueType@)"
"M:Acme.Widget.M2(System.Int16[],System.Int32[0:,0:],System.Int64[][])"
"M:Acme.Widget.M3(System.Int64[][],Acme.Widget[0:,0:,0:][])"
"M:Acme.Widget.M4(System.Int32)"
"M:Acme.Widget.M5(System.Object[])"

プロパティ。

Namespace Acme
    Class Widget
        Public Property Width() As Integer
            Get
            End Get
            Set (Value As Integer)
            End Set
        End Property

        Public Default Property Item(i As Integer) As Integer
            Get
            End Get
            Set (Value As Integer)
            End Set
        End Property

        Public Default Property Item(s As String, _
            i As Integer) As Integer
            Get
            End Get
            Set (Value As Integer)
            End Set
        End Property
    End Class
End Namespace

"P:Acme.Widget.Width"
"P:Acme.Widget.Item(System.Int32)"
"P:Acme.Widget.Item(System.String,System.Int32)"

イベント

Namespace Acme
    Class Widget
        Public Event AnEvent As EventHandler
        Public Event AnotherEvent()
    End Class
End Namespace

"E:Acme.Widget.AnEvent"
"E:Acme.Widget.AnotherEvent"

演算子。

Namespace Acme
    Class Widget
        Public Shared Operator +(x As Widget) As Widget
        End Operator

        Public Shared Operator +(x1 As Widget, x2 As Widget) As Widget
        End Operator
    End Class
End Namespace

"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"
"M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"

変換演算子には、後続の ~ の後に戻り値の型が続きます。

Namespace Acme
    Class Widget
        Public Shared Narrowing Operator CType(x As Widget) As _
            Integer
        End Operator

        Public Shared Widening Operator CType(x As Widget) As Long
        End Operator
    End Class
End Namespace

"M:Acme.Widget.op_Explicit(Acme.Widget)~System.Int32"
"M:Acme.Widget.op_Implicit(Acme.Widget)~System.Int64"