XML comments
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?
Odpovědi
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>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 folderC:\Documents and Settings\<user>\Application Data\Microsoft\VisualStudio\8.0This 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.- Označen jako odpověďLisa.FeigenbaumModerátor19. ledna 2009 23:32
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><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>
<developer/>
<summary/>
<param/>
<remarks/>
</Template>
<CompletionList>
<exception cref=""/>
<include file="" path=""/>
<param name=""/>
<permission cref=""/>
<remarks/>
<summary/>
<developer/>
</CompletionList>
</CodeElement>
<CodeElement type="Function">
<Template>
<developerXYZ/>
<summary/>
<param/>
<returns/>
<remarks/>
</Template>
<CompletionList>
<exception cref=""/>
<include file="" path=""/>
<param name=""/>
<permission cref=""/>
<remarks/>
<returns/>
<summary/>
<developerXYZ/>
</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>
Všechny reakce
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--*
- Zrušeno označení jako odpověďLisa.FeigenbaumModerátor19. ledna 2009 23:32
- 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
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>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 folderC:\Documents and Settings\<user>\Application Data\Microsoft\VisualStudio\8.0This 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.- Označen jako odpověďLisa.FeigenbaumModerátor19. ledna 2009 23:32
- Will this technique work for C# also?
No idea but I think this may be VB specific as the filename is VBXMLDoc.xml
- As ever, it's always embarassing to learn new things about your own product...
Ah, well... thanks, Spotty! 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
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><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>
<developer/>
<summary/>
<param/>
<remarks/>
</Template>
<CompletionList>
<exception cref=""/>
<include file="" path=""/>
<param name=""/>
<permission cref=""/>
<remarks/>
<summary/>
<developer/>
</CompletionList>
</CodeElement>
<CodeElement type="Function">
<Template>
<developerXYZ/>
<summary/>
<param/>
<returns/>
<remarks/>
</Template>
<CompletionList>
<exception cref=""/>
<include file="" path=""/>
<param name=""/>
<permission cref=""/>
<remarks/>
<returns/>
<summary/>
<developerXYZ/>
</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>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
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
- Zrušeno označení jako odpověďLisa.FeigenbaumModerátor19. ledna 2009 23:34
- 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! 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?
No this allows you to add the tags but not text between them.
- 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 Has anyone found out how to do the above posts nesting elements example?
Whoa, finally I was able to get rid of the <remarks> default tag. Thank you!- 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 - For me it worked in VS2008 / Vist 64 at this pathC:\Users\<username>\AppData\Roaming\Microsoft\VisualStudio\9.0\
