Partager via

How to Customize the XML Comments that are inserted by the Visual Basic Code Editor?

  • Article

Visual Basic XML Comments were first introduced in Visual Studio 2005. They can be used to create documentation for your project, and to provide a rich IDE experience for others using your code. For more information on XML Comments, please read my full article in MSDN Magazine here. This blog post focuses on the specific steps necessary to customize Visual Basic XML Comments.

XML Comments are used to comment members. When you type three single-quotation marks ('") immediately above the member definition and press Enter, the Visual Basic editor inserts an XML skeleton for you.

Before:

'''
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

After:

''' <summary>
'''
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <remarks></remarks>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

There is a specific default XML skeleton that gets inserted for each kind of member. However you may want to change the default XML Comments to match your company’s guidelines, or your own personal preferences. In order to help with these scenarios, Visual Basic provides a way to customize the default XML skeleton. Here’s how.

Create a new XML file called VBXMLDoc.xml, and copy the following code into that file. You can also download this file as an attachment to this post.

XML text to copy into VBXMLDoc.xml:

<?xml version="1.0" encoding="utf-8" ?>
<XMLDocCommentSchema>

  <CodeElement type="Module">
    <Template>
      <summary/>
      <remarks/>
    </Template>
    <CompletionList>
      <include file="" path=""/>
      <permission cref=""/>
      <remarks/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Class">
    <Template>
      <summary/>
      <remarks/>
    </Template>
    <CompletionList>
      <include file="" path=""/>
      <permission cref=""/>
      <remarks/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Structure">
    <Template>
      <summary/>
      <remarks/>
    </Template>
    <CompletionList>
      <include file="" path=""/>
      <permission cref=""/>
      <remarks/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Interface">
    <Template>
      <summary/>
      <remarks/>
    </Template>
    <CompletionList>
      <include file="" path=""/>
      <permission cref=""/>
      <remarks/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Enum">
    <Template>
      <summary/>
      <remarks/>
    </Template>
    <CompletionList>
      <include file="" path=""/>
      <permission cref=""/>
      <remarks/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Property">
    <Template>
      <summary/>
      <param/>
      <value/>
      <remarks/>
    </Template>
    <CompletionList>
      <exception cref=""/>
      <include file="" path=""/>
      <param name=""/>
      <permission cref=""/>
      <remarks/>
      <summary/>
      <value/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Sub">
    <Template>
      <summary/>
      <param/>
      <remarks/>
    </Template>
    <CompletionList>
      <exception cref=""/>
      <include file="" path=""/>
      <param name=""/>
      <permission cref=""/>
      <remarks/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Function">
    <Template>
      <summary/>
      <param/>
      <returns/>
      <remarks/>
    </Template>
    <CompletionList>
      <exception cref=""/>
      <include file="" path=""/>
      <param name=""/>
      <permission cref=""/>
      <remarks/>
      <returns/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Operator">
    <Template>
      <summary/>
      <param/>
      <returns/>
      <remarks/>
    </Template>
    <CompletionList>
      <exception cref=""/>
      <include file="" path=""/>
      <param name=""/>
      <permission cref=""/>
      <remarks/>
      <returns/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Declare">
    <Template>
      <summary/>
      <param/>
      <returns/>
      <remarks/>
    </Template>
    <CompletionList>
      <exception cref=""/>
      <include file="" path=""/>
      <param name=""/>
      <permission cref=""/>
      <remarks/>
      <returns/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Field">
    <Template>
      <summary/>
      <remarks/>
    </Template>
    <CompletionList>
      <include file="" path=""/>
      <permission cref=""/>
      <remarks/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Delegate">
    <Template>
      <summary/>
      <param/>
      <returns/>
      <remarks/>
    </Template>
    <CompletionList>
      <include file="" path=""/>
      <param name=""/>
      <permission cref=""/>
      <remarks/>
      <returns/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <CodeElement type="Event">
    <Template>
      <summary/>
      <param/>
      <remarks/>
    </Template>
    <CompletionList>
      <include file="" path=""/>
      <param name=""/>
      <permission cref=""/>
      <remarks/>
      <summary/>
    </CompletionList>
  </CodeElement>

  <ChildCompletionList>
    <c/>
    <code/>
    <example/>
    <list type="">
      <listheader>
        <term/>
        <description/>
      </listheader>
    </list>
    <para/>
    <paramref name=""/>
    <see cref=""/>
    <seealso cref=""/>
  </ChildCompletionList>

</XMLDocCommentSchema>

Save VBXMLDoc.xml to the appropriate location below, based on your version of Windows and Visual Studio. Please replace ‘<user>’ in the path with your own username.

Where to save VBXMLDoc.xml

VS 2005

VS 2008

 VS 2010

Windows XP

Windows Vista or Windows 7

Path

X

    

X

  

C:\Documents and Settings\<user>\Application Data\Microsoft\VisualStudio\8.0

X

      

X

C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\8.0
 

X

  

X

  

C:\Documents and Settings\<user>\Application Data\Microsoft\VisualStudio\9.0
 

X

    

X

C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\9.0
    X X  

C:\Documents and Settings\<user>\Application Data\Microsoft\VisualStudio\10.0
    X   X C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\10.0

When VBXMLDoc.xml is present, Visual Studio will use the definitions from that file, instead of the built in defaults, when inserting the XML Comment skeletons into the IDE. The version of VBXMLDoc.xml above (and attached) contains the built in defaults. To change the defaults, find the code element type you are interested in, and edit that element in the file. In this example, let’s change the XML skeleton that gets inserted for Function.

Default XML tags for Function

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <remarks/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <permission cref=""/>
    <remarks/>
    <returns/>
    <summary/>
  </CompletionList>
</CodeElement>

The Template element’s children represent the XML elements that will be inserted in the XML skeleton for a Function. The CompletionList element’s children represent the suggestions that will appear in intelliSense upon typing a left angle bracket (<) above a Function.

Let’s make the following changes:

· Remove the remarks element from both the default skeleton and intelliSense.
· Add an author element to both the default skeleton and intelliSense.
· Add a history element to intelliSense.

Here’s what the Function element in VBXMLDoc.xml will look like when we’re done.

Customized XML tags for Function

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <author/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <permission cref=""/>
    <returns/>
    <summary/>
    <author/>
    <history/>
  </CompletionList>
</CodeElement>

At this point you need to close and re-open Visual Studio, in order for VBXMLDoc.xml to get picked up. After restarting, the XML Comments automatically inserted above Function will include an author element instead of remarks.

Customized XML Skeleton for Function

    ''' <summary>
    '''
    ''' </summary>
    ''' <param name="regKey"></param>
    ''' <returns></returns>
    ''' <author></author>
    Function RegKeyExists(ByVal regKey As String) As Boolean
        Dim exists As Boolean = False
        Try
            If My.Computer.Registry.CurrentUser.OpenSubKey(regKey) IsNot Nothing Then
                exists = True
            End If
        Finally
            My.Computer.Registry.CurrentUser.Close()
        End Try
    End Function

 

 

In the image below, we can also see that a history element now appears in the list of options XML intelliSense offers for a function. (Although we also added an author element to appear in intelliSense, it doesn’t here because there is already an author element in the XML.)

Customized XML IntelliSense for Function

clip_image001

Please also note that while it is possible to add XML elements to the template, it is not possible to add XML values. Thus, you can make the IDE insert <author></author> by default; however, it is not possible to make it insert <author>Microsoft Corporation</author>.

VBXMLDoc.xml

Comments

  • Anonymous
    July 13, 2010
    Is it possible to define a template that uses sub elements with this file? For example: <history>  <entry author="">  </entry> </history>

  • Anonymous
    December 20, 2010
    I would like to know whether this same thing can be done for C# environment. If yes, then how can I do it?

  • Anonymous
    May 09, 2011
    VBXMLDoc.xml is a broken link in your referenced article

  • Anonymous
    July 11, 2011
    The list tag of the ChildCompletionList element is missing several tags. It should also have  term, description, and item tags, with the item tag having child elements of term and description.  The correct list tag should appear as follows: <list type="">    <term/>    <description/>    <item>        <term/>        <description/>    </item>    <listheader>        <term/>        <description/>    </listheader> </list> Joe Kunk MIcrosoft MVP Visual Basic Visual Studio Magazine ON VB columnist

  • Anonymous
    March 23, 2012
    This is great information! It is nowhere to be found in Visual Studio documentation. This is only available for Visual Basic, though. Here you can vote to have the feature included for C# too: visualstudio.uservoice.com/.../2709987-xml-comments-schema-customization-in-c-

  • Anonymous
    August 13, 2013
    Visual Basic should die already. Completely redundant and useless.

  • Anonymous
    September 03, 2014
    How do you get this to work in VS2012 Express. The file is not picked up by VS. What folder do I have to put the XML file in?

  • Anonymous
    May 13, 2015
    I need this functionality to work in VS 2013 , but I can make it work. Should it be working?

  • Anonymous
    September 16, 2015
    It was working fine in VS2013 (puting the file at C:UsersmyUserNameAppDataRoamingMicrosoftVisualStudio12.0 for Win8.1 and Win10), but the equivalent file in C:UsersmyUserNameAppDataRoamingMicrosoftVisualStudio14.0 seems to be ignored by VS2015. Has this feature been dropped?

  • Anonymous
    October 15, 2015
    Hi Mark, Did you get it to work in VS2015? I notice in VS2015 that under Options->Text Editor->Basic->Advanced there's a: Generate XML documentation comments for '''' option which when switched on only produces <summary> and <param> tags (for methods with parameters), but alas when switched off doesn't produce anything for ''' (with VBXMLDoc.xml in the Visual Studio14.0 directory). Brian

  • Anonymous
    October 18, 2015
    No not yet.

  • Anonymous
    November 08, 2015
    It's annoying! Such a wonderful feature doesn't work in the newest version of VS. I used the remarks section to document the latest change date and i found it very useful. Now its gone and the described file have obviously no effect. Further it seems that the tab button behavior also has been changed. WHY? It was good as it was.... In my personal opinion this function was supposed to make work with vs less annoying. Instead this, now i have to do more clicks as necessary and every time i have to do this i get a little more frustrated.... Is there someone, who can help me out of this misery???? With hopeful greetings. Steven PS Sorry for the bad english, i'm still learning :-)