Processing the XML File (Visual Basic)

The compiler generates an ID string for each construct in your code that is tagged to generate documentation. (For information on how to tag your code, see XML Comment Tags.) The ID string uniquely identifies the construct. Programs that process the XML file can use the ID string to identify the corresponding .NET Framework metadata/reflection item.

The XML file is not a hierarchical representation of your code; it is a flat list with a generated ID for each element.

The compiler observes the following rules when it generates the ID strings:

  • No white space is placed in the string.

  • The first part of the ID string identifies the kind of member being identified, with a single character followed by a colon. The following member types are used.

Character Description
N namespace

You cannot add documentation comments to a namespace, but you can make CREF references to them, where supported.
T type: Class, Module, Interface, Structure, Enum, Delegate
F field: Dim
P property: Property (including default properties)
M method: Sub, Function, Declare, Operator
E event: Event
! error string

The rest of the string provides information about the error. The Visual Basic compiler generates error information for links that cannot be resolved.
  • The second part of the String is the fully qualified name of the item, starting at the root of the namespace. The name of the item, its enclosing type(s), and the namespace are separated by periods. If the name of the item itself contains periods, they are replaced by the number sign (#). It is assumed that no item has a number sign directly in its name. For example, the fully qualified name of the String constructor would be System.String.#ctor.

  • For properties and methods, if there are arguments to the method, the argument list enclosed in parentheses follows. If there are no arguments, no parentheses are present. The arguments are separated by commas. The encoding of each argument follows directly how it is encoded in a .NET Framework signature.

Example

The following code shows how the ID strings for a class and its members are generated.

Namespace SampleNamespace

  ''' <summary>Signature is 
  ''' "T:SampleNamespace.SampleClass"
  ''' </summary>
  Public Class SampleClass

    ''' <summary>Signature is 
    ''' "M:SampleNamespace.SampleClass.#ctor"
    ''' </summary>
    Public Sub New()
    End Sub

    ''' <summary>Signature is 
    ''' "M:SampleNamespace.SampleClass.#ctor(System.Int32)"
    ''' </summary>
    Public Sub New(ByVal i As Integer)
    End Sub

    ''' <summary>Signature is 
    ''' "F:SampleNamespace.SampleClass.SampleField"
    ''' </summary>
    Public SampleField As String

    ''' <summary>Signature is 
    ''' "F:SampleNamespace.SampleClass.SampleConstant"
    ''' </summary>
    Public Const SampleConstant As Integer = 42

    ''' <summary>Signature is 
    ''' "M:SampleNamespace.SampleClass.SampleFunction"
    ''' </summary>
    Public Function SampleFunction() As Integer
    End Function

    ''' <summary>Signature is 
    ''' "M:SampleNamespace.SampleClass.
    ''' SampleFunction(System.Int16[],System.Int32[0:,0:])"
    ''' </summary>
    Public Function SampleFunction( 
        ByVal array1D() As Short, 
        ByVal array2D(,) As Integer) As Integer
    End Function

    ''' <summary>Signature is 
    ''' "M:SampleNamespace.SampleClass. 
    ''' op_Addition(SampleNamespace.SampleClass,
    '''             SampleNamespace.SampleClass)"
    ''' </summary>
    Public Shared Operator +( 
        ByVal operand1 As SampleClass, 
        ByVal operand2 As SampleClass) As SampleClass

      Return Nothing
    End Operator

    ''' <summary>Signature is 
    ''' "P:SampleNamespace.SampleClass.SampleProperty"
    ''' </summary>
    Public Property SampleProperty() As Integer
      Get
      End Get
      Set(ByVal value As Integer)
      End Set
    End Property

    ''' <summary>Signature is
    ''' "P:SampleNamespace.SampleClass.Item(System.String)"
    ''' </summary>
    Default Public ReadOnly Property Item( 
        ByVal s As String) As Integer

      Get
      End Get
    End Property

    ''' <summary>Signature is 
    ''' "T:SampleNamespace.SampleClass.NestedClass"
    ''' </summary>
    Public Class NestedClass
    End Class

    ''' <summary>Signature is 
    ''' "E:SampleNamespace.SampleClass.SampleEvent(System.Int32)"
    ''' </summary>
    Public Event SampleEvent As SampleDelegate

    ''' <summary>Signature is 
    ''' "T:SampleNamespace.SampleClass.SampleDelegate"
    ''' </summary>
    Public Delegate Sub SampleDelegate(ByVal i As Integer)
  End Class
End Namespace

See Also

/doc
How to: Create XML Documentation