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