frmSettings.vb
Update the form UI so that it looks like (Figure: VBCommenterSettings)
We will also need to use the openFileDialog control
The code for this form is pretty straight forward with the exception of launching NDoc.
In the first scenario we launch the NDoc GUI. This is accomplished by first ensuring the user browses for the install location of NDocGui.exe
The code to launch the application is contained in btnLaunchGUI_Click (see: Launch GUI)
The second approach is to select dlls from the solution by clicking the add button.
I use the Tag property of the Listbox to store a hashtable containing the full path to the dll, but only display the name within the view.
When the user clicks run, the full paths are retrieved and the command line arguments are built into a string and passed to the NDocConsole.exe. (see: btnRunNDoc_Click)
Template.vb
Because of the way the code is written in 'Template.vb", in order to use a flat file for configuration, it must contain a pointer to a file path of an Xslt for each type of structure the xslt is designed to handle, see line 14 -15
1. Public Shared
Function GetItemTypeTransformation(ByVal piTemplateType As
TemplateTypesEnum, ByVal psItemType As String, ByRef pbInternalResource As
Boolean) As String
2. Dim bOverridden As Boolean
3. Dim sRet As String
4. Dim sTemplateType As String
5.
Dim
oConfigFile As Xml.XmlDocument
6.
Dim
oNode As Xml.XmlNode
7. Dim sNodeLocation As String
8. Dim sPathResourceDirectory,
sSystemRoot As String
9.
10.Const sConfigFile As String =
"VBCommenterConfig.xml"
11.Dim xConfig As
XmlDocumentConfigImp
12.:
13.:
14.sNodeLocation =
"/config/templates/" + sTemplateType + "/" _
15.+ psItemType
16.oNode =
oConfigFile.SelectSingleNode(sNodeLocation)
17.bOverridden = False
18.:
19.:
In this section the code tries to find a particular node within the config file. If it's not found the code will then get the information out of the registry. In order to plug into this we need to provide a path to the Xml config file and the config file must contain the relative path to the Xslt which contains the code needed to transform the node.
The Xml configuration file will have to look like this:
<?xml version="1.0" encoding="utf-8" ?>
<config>
<templates>
<stub>
<class>signatures.xslt</class>
<delegate>signatures.xslt</delegate>
<enum>signatures.xslt</enum>
<function>signatures.xslt</function>
<interface>signatures.xslt</interface>
<namespace>signatures.xslt</namespace>
<property>signatures.xslt</property>
<struct>signatures.xslt</struct>
<typedef>signatures.xslt</typedef>
<variable>signatures.xslt</variable>
<eventsdeclaration>signatures.xslt</eventsdeclaration>
<event>signatures.xslt</event>
<default>signatures.xslt</default>
</stub>
</templates>
</config>
Notice that all the constructs point to the same Xslt file, "signatures.xslt."
It would be possible to point each construct to its own Xslt file but that won't be necessary since it fairly straightforward to handle in one file.
Next we will need to create our Xslt file. I've based my file on the "default-autoinsert.xslt" that is located in the templates sub directory of the project.
(see autoinsert.xslt)
Not the authors have inserted predefined constants that are replaced in code after the transform. This replacement is handled in VBCommenter.vb's GenXMLDocStub method. The following replacement characters have been defined:
* [TAB] Code Replacement: vbTab
* [CRLF] Code Replacement: vbCRLF
* [TRICK] Code Replacement: ""
* [CURSOR] Code Replacement: "" - used only within "summary" to find a
position within the string.
[TAB], [CRLF], and [TRICK] are not needed for generating the Xml Documentation but help with the positioning of rendered text and line breaks within the code text editor. Again, the replacement of these characters occurs after the Xsl Transform.
So that we can customize the output from the style sheet we will need to accept the following input parameters to the style sheet. This is done by simply adding a few param statements at the top of the document (see Adding Params, lines 5-7)
In order to pass param will need to modify Utils.vb to accept params (see apply transform)
Note: line 364 we add the input parameter oXslArgumentsList so that xslt input parameters can be passed to this method
Also note lines 390 and 392 where I changed "nothing" to this input XslArgumentlist
One other place that will need to be updated is Template.vb's GetFilledXMLTemplateForCodeElement method. Here we will create the arguments list, add Current year, and retrieve from the configuration "client name" and "showHistory" flag. (see GetFilledXMLTemplateForCodeElement, 538-543)
Next we need to take a look at the xml that the xslt stylesheet is designed to be used against, so that we can get a better handle on what data is available.
Here is the Xml generated internal to the application for a subroutine:
<xmldocinfo>
<project>MyProject</project>
<date>1/19/2004</date>
<time>5:33:52 AM</time>
<userid>coelhop</userid>
<machinename>MyMachine</machinename>
<name>Enumerations.subTest</name>
<fullname>MySolution.Enumerations.subTest</fullname>
<is-type value="false" />
<code-element-type>function</code-element-type>
<arguments>
<argument>
<name>TestSub</name>
<typename>String</typename>
<typefullname>System.String</typefullname>
<byref>false</byref>
</argument>
</arguments>
</xmldocinfo>
A subroutine is defined as having "code-element-type= function" and no "return" node.
The following is the Xml generated for a function:
<xmldocinfo>
<project>MyProject</project>
<date>1/19/2004</date>
<time>5:33:38 AM</time>
<userid>coelhop</userid>
<machinename>MyMachine</machinename>
<name>Enumerations.strTest</name>
<fullname>MySolution.Enumerations.strTest</fullname>
<is-type value="false" />
<code-element-type>function</code-element-type>
<return>
<returntypename>Int32</returntypename>
<returntypefullname>System.Int32</returntypefullname>
</return>
<arguments>
<argument>
<name>sTest</name>
<typename>String</typename>
<typefullname>System.String</typefullname>
<byref>false</byref>
</argument>
</arguments>
</xmldocinfo>
note the return node
The following is Xml generated for a class:
<xmldocinfo>
<project>VBCommenter</project>
<date>1/18/2004</date>
<time>10:39:49 AM</time>
<userid>coelhop</userid>
<machinename>MyMachine</machinename>
<name>Template</name>
<fullname>VBCommenter.Template</fullname>
<is-type value="true" />
<code-element-type>class</code-element-type>
</xmldocinfo>
The Xml for the other contructs are very similar to those displayed here.
In updating the Xslt, I decided to move the generation of the "header" to a named template so that it could act like a function and return a different string based on the input param "Client" (client name). So if no client name is supplied the default dashed line is returned, otherwise the copyright header is returned.
I applied the same logic to the history section. It would be easy to apply this logic to the exception section also and make its presence configurable too ( I leave that as an exercise to the reader.)
I added the exception tag to the comment section and also made the data returned for "param" and "return" more verbose so that it matched my requirements.
The most important piece is having the VBCommentConfig.xml and at least one corresponding Xslt file at a predetermined path on the hard drive. Once you have the application reading from that source, it's relatively easy to totally transform the look and feel of the comment sections to your own needs with just a little xslt.
Setup
So far we've examined code commenting and the code changes made to make the VBCommenter add-on configurable, now lets go over setting it up:
- Download VBCommenter setup
- Ensure that all versions of Visual Studio are closed.
- Run "VBCommenterSetup.msi"
- ensure that "VBCommenterConfig.xml" and "signatures.xslt" are at:
%systemroot%\Microsoft.NET\PowerToys for Visual Studio .NET 2003\VBCommenter\ Resources
If these files are not there, try logging in as Administrator and running the installation again.
- goto sourceforge and download the web installer "NDocSetup.Exe"
- while connected to the internet, run "NDocSetup.Exe" this will download and install the latest version of NDoc (currently 1.2)
Commenting Your Code
- Open Visual Studio
- Open an existing VB.NET project
- Add some comments by typing three apostrophe characters just before a code construct (e.g. class, function, property, etc.)
- Rebuild the project
- You should notice two new xml files with the same name as the project. One will be in the child directory or the project, this is a temp file. The real file will be located next to the dll in the bin directory. By default this file is rewritten everytime the project is built.
Walk through running NDoc from within Visual Studio
- On the "standard toolbar" at the top locate "Tools" select this then "VBCommenter Options" the settings form will open. (see figure VBCommenterSettings)
- The first time this is launched you will need to tell it where the NDocConsole.exe application is.
- Ensure the checkbox "Use NDoc to Dynamically Generate MSDN style compiled help file", is checked.
- Click the Browse button a navigate to NDocConsole.exe. The default path is "Program Files\NDoc\bin\.net-1.1\NDocConsole.exe" this may be different on your machine.
- In the NDoc Procedures section click the "add" button this will launch a FileOpenDialog - use this to navigate to and select the dll for the project you just added comments to. (note: you can add several dll's from different projects and solutions)
- Click "Run"
- A FileSaveDialog will be launched asking where you want to save the output files to. Make you selection and click ok
- You should see a command prompt giving you feedback as the process runs. In a short while you will find in the folder you selected, several HTML pages (similar to "Tools --> Build Comment Web Pages...") to launch the website, double click on "index.htm"
- You should also find a file called "Documentation.chm" this is the compiled windows help file which is a standalone version of the same information.
Walk through launching NDoc from within Visual Studio
- On the "standard toolbar" at the top locate "Tools" select this then "VBCommenter Options" the settings form will open. (see figure VBCommenterSettings)
- The first time this is launched you will need to tell it where the NDocGUI.exe application is.
- Ensure the checkbox "Use NDoc GUI", is checked.
- Click the Browse button a navigate to NDocGUI.exe. The default path is "Program Files\NDoc\bin\.net-1.1\NDocGui.exe" this may be different on your machine.
- Click Launch
- For more information on using NDoc see: http://ndoc.sourceforge.net/resources.html
