customizing your vs.net 2005 vb.net xml documentation templates

With the release of vb.net 2005, Microsoft added support for xml documenation tags, a useful feature that c# had had for a few versions. Whilst you could use the documentation tags in vb.net in vs.net 2003, you had to install the vbcommentator powertoy, it's always nicer when support is baking into the IDE itself. To generate documentation templates, you simply have to type three apostrophies i.e. ''' , and vs.net will generate the context and generate the stub i.e. if it's beside a property, it'll generate the approriate xml tags for that area.

Whilst the default's are pretty good, often you'll have a need to alter them, perhaps to match your coding standards (e.g. I often use the <example> and <code> tags to provide guidance to users of my API's), and it's not obvious how to do this as the default aren't exposed via the UI, but you can override them by providing your own implementation in a particular location.

If you're running vs.net 2005, and you're a vb.net developer, create a file called VBXMLDoc.xml, and place a copy of it in your \Documents and Settings\<your user>\Application Data\Microsoft\VisualStudio\8.0 folder and you should be set. Below is a copy of the vs.net 2005 vb.net defaults that should be easy to tweak for your own needs.

<?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/>
        </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>

Print | posted on Saturday, November 04, 2006 3:29 AM

Feedback

No comments posted yet.

Your comment:





 
Please add 3 and 6 and type the answer here:

Copyright © Cathal Connolly

Design by Bartosz Brzezinski

Design by Phil Haack Based On A Design By Bartosz Brzezinski