Definition file

To override set of Visual Basic XML Doc Comments tags known to IntelliSense it is necessary to create special XML file, that defines for each type of member

• Default comment to appear when ''' is typed.
• Tags suggested for that type member by IntelliSense

• C:\Documents and Settings\<user>\Application Data\Microsoft\VisualStudio\<version>\VBXMLDoc.Xml (for Windows XP)
• C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\<version>\VBXMLDoc.xml (for Windows Vista and later)

File structure

The file is ordinary XML file (no XML-Schema or something like that). File defines for each type of code element default XML Doc template and set of allowed tags with their parameters. Visual Basic IntelliSense treats some tags and attributes in special way. This logic is built-in in Visual Basic IntelliSense provider and cannot be redefined in the XML file. For example element <param name=""/> is offered for each parameter of member with parameters. <typeparam name=""/> is offered for generic parameters. Attribute name of <paramref> element offers name of parameters of actual element. cref attribute of any element offers references to other types and members. And it seems that cref attribute of any element is also processed by Visual Basic compiler, so context-relative reference is turned to fully qualified reference with member type specifier.

The file does not use XML namespaces.

<XMLDocCommentSchema>

Root element of VBXMLDoc.Xml

Attributes:none

Children: <CodeElement>{0,∞}; <ChildCompletionList>{1}

<CodeElement>

Defines template and available tags for specified code element (as class, property, delegate etc.)

Parents: <XMLDocCommentsSchema>

Attributes: type - type of code element this tag defines XML tags for (see below for list of values)

Children: <Template>{1}, <CompletionList>{1}

Types of elements:

• Module Visual Basic [Standard] Module (static class; Module keyword)
• Namespacenot used
• Class Class (reference type; Class keyword)
• Structure Structure (value type; Structure keyword)
• Interface Interface (Interface keyword)
• Enum Enumeration (Enum keyword)
• Property Property (Property keyword)
• Sub Procedure - method without return value and type initializers and constructors (Sub keyword)
• Function Function - method with return value (Function keyword)
• Operator Operator - special function used for operations like adding, multiplying or type conversions (Operator keyword))
• Declare Visual Basic import of native procedure or function (Declare keyword)
• Field Field (instance/type variable; Dim keyword)
• Delegate Delegate declaration both - Sub and Function (Delegate keyword)
• Event Event - all 3 possible syntaxes (Event keyword)

Defines template of XML documentation as it appears when ''' is typed on line preceding member header.
Parents: <CodeElement>
Attributes:none
Children:any{0,∞}
Child elements of this element specify XML content to appear when ''' is typed on line preceding member header. This is really template rather than exact comment. Elements are specified as empty elements with empty attributes. For example <summary /> or <param name=""/>. <summary> element is always expanded to 3 lines. <param> and <typeparam> elements are placed as many times as necessary and their name attributes are filled with names of arguments / type parameters of given member.

Defines list of top-level elements and their attributes to be offered by IntelliSense when typing XML Doc comments for particular member.
Parents: <CodeElement>
Attributes:none
Children:any{0,∞}
Child elements of this element specify top-level elements offered by Visual Basic IntelliSense when typing XML Doc Comments for particular kind of member. Elements are specified as empty with empty attributes. Any possible children of child elements are ignored as well as attribute values.

Defines list of generl-purpose elements offered by Visual Basic IntelliSense when typing content of top-level elements in XML Doc Comments.
Parents: <XmlDocCommentSchema>
Attributes:none
Children:any{0,∞}
Child elements of this element specify elements offered by Visual Basic IntelliSense when typing content of top-level elements. Thos elements should be general-purpose as there is now way how to specify that e.g. element <note> can appear only in <remarks> top-level element. Elements are usually specified as empty with empty attributes. Any attribute values are ignored.
Child elements of child elements specify elements that can appear inside their parents in addition to general-purpose ones. Same rules apply as with general-purpose elements and children of children of children are allowed as well.

Examples

Following example shows definition suitable for Class member:

<CodeElement type="Class">
    <Template>
        <summary />
        <typeparam />
    </Template>
    <CompletionList>
        <include file="" path="" />
        <permission cref="" />
        <remarks />
        <summary />
        <completionlist cref=""/>
        <seelaso cref=""/>
        <exclude/>
        <preliminary/>
        <threadsafety/>
        <inheritdoc cref="" select=""/>
        <typeparam name="" />
        <filterpriority/>
    </CompletionList>
</CodeElement>

Following example shows foll code of <ChildCompletionList> section:

<ChildCompletionList>
    <c />
    <code lang="" />
    <example />
    <list type="">
        <listheader>
            <term />
            <description />
        </listheader>
        <item>
            <term />
            <description />
        </item>
    </list>
    <para />
    <paramref name="" />
    <see cref="" langword="" />
    <IPermission class="" version="" Flags=""/>
    <typeparamref name=""/>
    <note type=""/>
</ChildCompletionList>

Dim col As Color
Col = |

<completionlist cref="T:System.Drawing.Color" />

Example

''' <completionlist cref="KnownCssAttributes"/>
Public Class CssAttribute
    Public Sub New (ByVal Name$)
    End Sub
    Public Shared Widening Operator CType(ByVal cssName$) As CssAttribute
        Return New CssAttribute(cssName)
    End Operator
End Class

Public Module KnownCssAttributes
    Public ReadOnly BackgroundColor As CssAttribute = New CssAttribute("background-color")
    Public ReadOnly Property Padding As CssAttribute
        Get
            Return New CssAttribute("padding")
        End Get
    End Property
    Public Const MozBorderRadius$ = "-moz-border-radius"
End Module

Now when you type something like

Dim h As CssAttribute = |

Remarks

• Type in cref attribute of <completionlist> may be or may be not same type as type <completionlist> is applied onto.
• Type in cref attribute of <completionlist> can be any kind of type - Structure, Class, Enumeration, built-in type like Integer (delegates and interfaces do not apply since they cannot have public static fields/properties).
• IntelliSense offers all accessible static (Shared) members of type specified in cref, even such members type of which is not suitable for target. You there is not CType in example above, error occurs for MozBorderRadius though IntelliSense still offers it.
• When <completionlist> is applied on certain type, IntelliSense offers only members of type specified in cref (as described above) and programmer has difficulties typing other values like locals of target type.