The XML comment stub that gets inserted when you press '''<return> in front of a code element can be customized. The same applies to the XML string you get in the resulting XML comment file if you have not commented a element and the setting GenerateNotDocumentedComments is set to true.

The customization can be done by making your own template that will be used when the stub and/or not documented comment should be generated. From now on we will refer to this as a stub. A template is a XSLT template that get's applied to a XML document with a prefedined structure. The add-in let's you specify what template you want to use in the Templates dialog. You find the Template dialog on the menu under 'Tools | VBXC - VB.NET XML Commentor | Templates ...'. Here you can specify templates for different kind of code-elements and stubs or you can choose to let the add-in use the default built-in template.

What happens is that when a stub needs to be generated, the add-in generates a XML document describing the CodeElement the stub should be generated for. The add-in then looks in the settings on what template to use. It then applies the correct template to the XML document. If the stub is a XML comment stub the add-in prefixes each line with the XML comment prefix. If the stub is a not commented stub it is written directly to the output file. The result of the transformation should be valid XML, but can contain multiple root elements. The add-in does not verify this, but if the result is not valid XML you will get warnings when the add-in generates the XML file and/or the generated XML file will not be a valid XML file.

In order to make a XSLT template you need to know the structure of the XML document the template should transform.

The document has the following DTD:

Description of the different elements:

date
Contains the current date in the ddmmyyyy format

time
contains the current time in the hhmmss formar

userid
username of the computer user currently logged in

machinename
name of the computer running VS.NET

name (top level)
Name of the element that is beeing described (short name)

fullname
Name of the element that is beeing described (full name including full namespace)

curdesc
If VBXMLDoc was able to extract any description for the CodeElement this is provided here. If no description is available this element will be omitted. Currently it tries to fetch description from any System.ComponentModel.Description and System.Web.Services.MethodDesc attribute that is attached to the CodeElement.

is-type
The value is set to true if this CodeElement represents a CodeType (Struct, Delegate, Class or Interface)

code-element-type
A string representation of the type this CodeElement is. It contains one of the following values: class, delegate, enum, function, interface, namespace, property, struct, typedef, variable, eventsdeclaration, event

return
If the code element returns something this element exists and describes the type of the value the CodeElement returns

returntypename
The short typename of the return value

returntypefullname
The full typename of the return value (including full namespace)

name (argument level)
The name of the argument

typename
The short typename of a argument

typefullname
The long typename of a argument (including full namespace)

byref
Contains the value 'true' if the argument is a byref argument 'false' otherwise

argument
Describes a argument to the code element

arguments
Contains a list of arguments the code element has. If the code element does not have any arguments this element is omitted

Special strings that can be used in the template output
All strings are enclosed in square brackets and must be uppercase.

[TAB]
Get's replaced by a tab character before the XML is inserted in the text editor or output document

[CRLF]
Get's replaced by a linebreak before the XML is inserted in the text editor or output document

[TRICK]
Get's removed before the XML is inserted in the text editor or output document (this is to have a way of forcing the XSLT engine to keep linebreaks as it does keep them in #PCDATA sections)

[CURSOR]
Should only be used for XML comment stub templates. This special string get's removed before the stub is inserted into the code, but marks where the cursor should be placed after the stub is inserted.

Is there any example templates available?
In the folder where you installed VBXC you find the two default templates VBXC uses. The name of the files are default-autoinsert.xslt and default-notcommented.xslt. If you make improvements to these or create new ones that you want to share with others send them to vbxc@tor-erik.net.

How to test your templates
In order to make it simpler to test your templates there is a template tester named XSLTTemplateTester that is installed in the folder where you installed VBXC. It is provided with source so that you can modify it to your needs (if you improve it please send the improved version to vbxc@tor-erik.net). It can be used in the following way:

• Select the type of code element you would like to test your template on (e.g. Class)
• Type in the name of the element (e.g. Class1)
• Select if the code element should have arguments (only available if the code element has support for arguments) (if set to yes three arguments will be described: argumentOne, argumentTwo and argumentThree)
• If the code element type has support for returning something the 'Returns' field will be available. Type the full name of the return type here (e.g. System.String)
• If you want to supply a description that could have been found in a attribute, write the description into the 'Description in attribute' field
• Now you should see the XML description of the code element in the 'input' textarea
• Paste your template into the 'template' textfield
• Press the 'Transform' button
• Now you should see the resulting