If the VBCommenter is so good, why do we need to modify it?
The VBCommenter has a default code heading section that contains generic Xml markup. Although it contains a little more than C#, it could easily do more. The existing markup generated for a method looks something like this:
'''
-------------------------------------------------------------
''' <summary>
'''
''' </summary>
''' <param
name="name"></param>
''' <remarks>
''' </remarks>
''' <history>
''' [logged
in user] mm/dd/yyyy Created
''' </history>
'''
-------------------------------------------------------------
Function
GetSetting(ByVal name As
String) As String
As consultants we work with many different clients. At Equarius, we have a coding standard where we display a copyright header which contains the client name at the top of each comment. It looks something like this:
*****************************************************************
Copyright [Current year] [client name]. All rights reserved.
*****************************************************************
We also have a history section to track code changes, which looks something like this:
Revision History:
-----------------------------------------------------------------
Date Name Description
-----------------------------------------------------------------
mm/dd/yyyy [developer] [free form text]
We may also want to automate the inclusion of other Xml markup such as:
''' <exception cref="System.ApplicationException">
''' Thrown when...
''' </exception>
Or add more details to the Param node such as:
''' <param name="name">
''' [description goes here].
''' Value Type: <see cref="String" /> (System.String)
''' </param>
Or add a returns section for functions
''' <returns><see cref="String" />(System.String)</returns>
The automated markup I would like inserted for a method would look like this:
'''
***********************************************************
''' Copyright [year] [client name]. All rights reserved.
'''
***********************************************************
''' Class.Method: IConfigProvider.GetSetting
''' <summary>
'''
''' </summary>
''' <param name="name">
''' [description
goes here].
''' Value
Type: <see cref="String" /> (System.String)
''' </param>
''' <param
name="defaultValue">
''' [description
goes here].
''' Value
Type: <see cref="String" /> (System.String)
''' </param>
''' <exception cref="System.ApplicationException">
''' Thrown
when...
''' </exception>
''' <returns><see
cref="String" />(System.String)</returns>
'''
<remarks><para><pre>
''' RevisionHistory:
'''
-----------------------------------------------------------
''' Date Name Description
'''
-----------------------------------------------------------
''' mm/dd/yyyy [logged in user] Initial
Creation
'''
''' </pre></para>
''' </remarks>
'''
-----------------------------------------------------------
Function GetSetting(ByVal name As String) As String
Note the use of the <see cref= "x" /> and <exception cref= "y" ></exception>.
In both cases the "cref" attribute is used to create a link reference in the generated documentation to the type "crefed."
Also notice the remarks node contains <para><pre> then the history followed by </pre></para>. "Para" is defined in the "Recommended Tags for Documentation Comments" in MSDN, while "pre" is an HTML markup tag that allows text to be rendered as is. Using the "pre" tag enables the table-like structure of the History section to be preserved when rendered as HTML in the generated documentation while keeping the section easy to update without the developer having to insert HTML markup.
Over time we may want to change this structure, and for each client we will want to change the comment heading to reflect the new client name. It doesn't make sense to open the code, make the adjustments, and re-install the VBCommenter each time this needs to be updated. This is why I modified the VBCommenter so that much of this is configurable.
1. Goals for this project:
a. Make the comment headers configurable without having to rebuild the msi and uninstall/reinstall the add-on.
b. Create a more robust comment header section.
c. Add to the simple customizations that can be managed from within the IDE, specifically:
1. Enable/disable copyright headers
2. Set Client Name
3. Enable/disable history block
d. Enable rudimentary automation of NDoc from within the IDE.
e. Enable Launching of the full NDoc GUI from within the IDE.
f. Make as few code changes to the existing code base as possible, so that upgrading to the next version will go smoothly.
2. Design decisions
a. Maintain a configuration Xml, and Xslt file in a predefined location
1. Update the setup utility so that it will create the following folder structure and copy the default documents: "VBCommenterConfig.xml" and "signatures.xslt" to it.
..\Microsoft.NET\Power Toys For Visual Studio 2003\VBCommenter\Resources
2. The existence and format of these files are dictated by existing code structures.
Overview of the code
The VBCommenter project is made up of the following:
/templates
default-autoinsert.xslt
- An Xslt style sheet that creates the header section based off an in memory xml representation of the method signature.
Configuration.vb
- Contains classes and interfaces that enable reading and writing to a configuration. In the current implementation the configuration is read from and written to the registry. There is some evidence of an earlier version that did use an Xml file.
Connect.vb
- This contains the classes, methods, and interfaces used to interact with the development environment.
frmSettings.vb
- A windows form that is launched when the user selects "Tools" --> "VBCommenter Options", it enables the user to enable or disable the following:
- Creation of the Xml document file with each build.
- Auto insertion of Xml comments
- Auto insertion of the history section with the Xml comments.
It also enables the developer to select from: '@, ', or ''' as the character sequence needed to generate the Xml comment section.
Template.vb
- This contains the classes and methods that gather information about the environment and the construct signature; it builds an xml document containing all these.
TextInsertion.vb
- This is the class that monitors keystrokes and document position, and handles the writing of each line of the comment section.
Utils.vb
- Contains several utility functions including the function that applies an Xslt style sheet to the Xml document containing all the meta data about the construct and its environment.
VBCommenter.vb
- This contains methods that determine if a header should be written, calls the appropriate methods in Template, TextInsertion, and Utils. It also receives the result from the Xsl transform handled in Utils and does further clean-up of the text prior to sending it to the page.
XMLWriter.vb
- Contains the methods used to build the in memory Xml document containing the signature metadata.
We will touch code in only the following files:
Configuration.vb - will add a few new keys to store and retrieve.
frmSettings.vb - will add the following to this UI
- CheckBox Add Copyright section
- Textbox setClientName
- OpenFileDialog to help set, retrieve, and store the path to the NDocGui.exe and the NDocConsole.exe
- ListBox to add and remove dll names to (NDoc needs to know the path's to the dll that will be included in the documentation.)
- Run button to execute the command line call to NDocConsole.exe
Template.vb - will modify a few lines so that it first attempts to load configuration data from the file we write to the hard drive, before looking in the registry.
Utils.vb - will modify the ApplyXSLTransformation method call so that it can accept an XsltArgumentlist (used for passing parameters to an Xslt)
We will be creating two new files:
- VBCommenterConfig.xml
- signatures.xslt
Configuration.vb
The configuration class contains predefined keys and read write properties that enable storing and retrieving data to and from the registry We will be adding three new keys (see Figure: Configuration keys lines 26 -28):
- keyClientNameForHeader
- keyNDocGUIPath
- keyNDocConsolePath
And the corresponding properties (see Figure: Configuration Properties)
This will enable us to retrieve and set these values from "frmSettings.vb.'
<< Introduction • • frmSettings.vb >>
