Changing the default comment structure for Visual Studio 2005

  • Thread starter Thread starter eedarley
  • Start date Start date
E

eedarley

Key Words: Visual Studio 2005, comment, comments, template, modify,
change, VS2005
Related Links: http://blog.developers.ie/cconnolly/archive/2006/11/04/2515.aspx,
and
http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=321766&SiteID=1

Purpose: I needed to change my existing comment structure for a
particular project I was on and wanted to share with the community how
it can be done. I searched heavily on Google and had little luck with
the exception of the referenced links.

Description: First, in order to customize the comment structure for
your vb apps you need to add a new XML file called "VBXMLDoc.xml"
located in \Documents and Settings\<user name>\Application Data
\Microsoft\VisualStudio\8.0\

Add the following content to the file to mimic the existing comment
structure

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


The current comment template for a PROPERTY is as follows:

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

Which would produce a comment section:
''' <summary>
'''
''' </summary>
''' <value></value>
''' <remarks></remarks>


I wanted it changed so that it would show as

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


This would produce a comment section that looks like this:
''' <datanumber></datanumber>
''' <summary>
'''
''' </summary>
''' <record></record>
''' <format></format>
''' <dprule></dprule>
''' <value></value>
''' <remarks></remarks>
 
(e-mail address removed) wrote in
Key Words: Visual Studio 2005, comment, comments, template, modify,
change, VS2005
Related Links:
http://blog.developers.ie/cconnolly/archive/2006/11/04/2515.aspx, and
http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=321766&SiteID=1

Purpose: I needed to change my existing comment structure for a
particular project I was on and wanted to share with the community how
it can be done. I searched heavily on Google and had little luck with
the exception of the referenced links.
Click to expand...

If you need to make customizations to documentation, you could use another
documentation engine like nDoc.
 
Back
Top