XML comments

Tue, 28 Mar 2006 22:53:15 Z

My group is attempting to standardize on XML commenting for all of our classes and methods. We like the "Insert comments" option in VS 2005 but would like to add an additional tag <history> to the comments section. I know that we could probably do this manually each time we add a new class, but I would like to be able to have this new section come up automatically when we insert the comment.

Is there a way to modify the XML comment block that is produced when you use the "Insert comment" function so that the new <history> tag will be included in the text?

XML comments

Wed, 29 Mar 2006 17:52:54 Z

Hi, awperli,

No, unfortunately that functionality is not in the product -- sorry about that. The idea of having a readable template for this is a great idea, though -- I'll add it to the list for consideration in (as we term it) "a future product release."

--Matt--*

XML comments

Wed, 29 Mar 2006 18:03:10 Z

Although that functionality does not exist in the product today , it would not be that difficult to create a macro that would auto insert the tag for you

XML comments

Wed, 29 Mar 2006 22:27:35 Z

Here's how to do it.... although its not something that is not accessible directly from the the IDE

Create a file call VBXMLDoc.Xml with the following contents

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

- <XMLDocCommentSchema>

- <CodeElement type="Module">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Class">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Structure">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Interface">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Enum">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Property">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Sub">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Function">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Operator">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Declare">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Field">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Delegate">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <CodeElement type="Event">

- <Template>

</Template>

- <CompletionList>

</CompletionList>

</CodeElement>

- <ChildCompletionList>

<c />

- <list type="">

- <listheader>

</listheader>

</list>

</ChildCompletionList>

</XMLDocCommentSchema>

Now that you have this file - you'll notice that in the Function Element that an additional tag <developer/> has been added. This will be the new tag for this xml comment.

Now add this file to the following folder

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

This will probably be hidden and you'll need to set the explorer to show the hidden files/folders.

Now open Visual Studio, create a project and use the ''' above a function and you'll notice that the new developer tag is added to the xml comments.

XML comments

Fri, 31 Mar 2006 04:19:37 Z

Will this technique work for C# also?

XML comments

Fri, 31 Mar 2006 05:05:26 Z

No idea but I think this may be VB specific as the filename is VBXMLDoc.xml

XML comments

Fri, 31 Mar 2006 16:21:14 Z

As ever, it's always embarassing to learn new things about your own product... Ah, well... thanks, Spotty!

XML comments

Tue, 04 Apr 2006 20:08:12 Z

spotty,

I tried your suggestion and nothing changed. I still get the same comments as I got before. I do not see the added "developer" tag in the comments for a function. Am I missing a step somewhere, like telling VS 2005 to look at the VBXMLDoc.Xml file for it's comment schema?

Tony

XML comments

Tue, 04 Apr 2006 21:21:23 Z

You need to ensure this file is in the correct location. In my case as my user is ABOWLES this would be the folder I would be looking at. You folder structure may be different.

D:\Documents and Settings\ABOWLES\Application Data\Microsoft\VisualStudio\8.0

The filename will be VBXMLDoc.xml in this folder.

And the entire contents of my file after re-verifying with a different XML tag for function is as follows. You'll notice I've highlight changed/additional lines the red.

This works on VSTS - which product SKU are you using.

The location and content of this file is critical for this to work. Once place here you will need to restart visual studio. Close all instances and start up again.

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

XML comments

Tue, 04 Apr 2006 22:18:13 Z

Spotty,

My user id is awperli so I put it in C:\Documents and Settings\awperli\Application Data\Microsoft\VisualStudio\8.0 and I used the name VBXMLDoc.Xml. I am using VS2005 Professional. I do not know what the SKU is or what you are referring to when you say VSTS.

I created the XML file by copying your original text and pasting it into a notepad file and saving it as VBXMLDoc.Xml.

I did shut down VS and restarted it after I copied the file to the above location.

Is this VBXMLDoc.Xml file possibly located somewhere else? I did not see it when I looked in the Documents and Settings location that you specified. I simply copied the file that I created into the subdirectory.

Also, you can contact me directly through my email at: awperli@sandia.gov

Tony

XML comments

Wed, 05 Apr 2006 00:52:53 Z

OK Spotty, for some reason it worked with the new text that you provided. I probably screwed something up during my first attempt. Thanks again.

Tony

XML comments

Wed, 19 Apr 2006 21:36:45 Z

How did you obtain this work around for VB? I would like to try and do this for C#.

I did try renaming the file to a couple of different names and taking out some of the elements that wouldn't work for C#, but I couldn't get it to work for C#. I did get it to work for VB without any problem, so thanks for the VB help!

XML comments

Tue, 30 May 2006 05:38:09 Z

Hi Spotty and Tony

This was the details I was looking for so long. Can we add text i.e project name or copyright details automatically using this, way vbCommenter inserts for the vb comments?

XML comments

Tue, 30 May 2006 14:25:55 Z

No this allows you to add the tags but not text between them.

XML comments

Tue, 27 Jun 2006 03:32:44 Z

has anyone had any luck with doing somethng like the following:

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

And then having the ide show the nested <example> when you first enter '''? The above will add the nested <example> when you start typing with in <examples> - which is shown by default. By I would like it the by default show <examples><example></example></examples>

Thanks

XML comments

Fri, 04 Jan 2008 04:31:54 Z

Has anyone found out how to do the above posts nesting elements example?

XML comments

Fri, 09 May 2008 10:01:46 Z

Whoa, finally I was able to get rid of the <remarks> default tag. Thank you!

XML comments

Wed, 25 Feb 2009 15:11:23 Z

Hi,

I'm running VS2008 under vista and cannot make the fix above work for me. Anyone know whether it still works in VS2008 and if so where the XML file now needs to be placed in vista/vs2008?

thanks in anticipation

Duncan

XML comments

Wed, 10 Jun 2009 19:17:40 Z

For me it worked in VS2008 / Vist 64 at this path

C:\Users\<username>\AppData\Roaming\Microsoft\VisualStudio\9.0\