This article was originally published by Đonny as IntelliSense for custom tags community content contribution on MSDN page Recommended XML Tags for Documentation Comments (Visual Basic).

IntelliSense for custom tags

Tools for processing XML comments like SandCastle can benefit from more tags than official tags mentioned in this article. You may even force the tool to process you own tags.
If you want Visual Studio to offer you your own set of tags when typing XML comments in Visual Basic or if you want your custom tags to appear when you type ''' in front of member, it is possible to setup your configuration.

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

Additionally it also defines set of generl purpose tags to be used inside another tags.
The file is located in user profile folder:
Version is 8.0 for Visual Studio 2005, 9.0 for 2008 and 10.0 for 2010.
Bear in mind that by specifying this file original built in set of XML comments is entirely replaced by the one specified in it.

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:

<Template>
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.
<CompletionList>
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.
<ChildCompletionList>
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>