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 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
Change History
Date |
History |
Reason |
---|---|---|
July 2008 |
Revised code example. |
Customer feedback. |