Processing the XML File (Visual Basic)

  • Article

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 Recommended XML Tags for Documentation Comments (Visual Basic).) 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

Tasks

How to: Create XML Documentation in Visual Basic

Reference

/doc