One of the must have tools for any C# programmer has to be NDoc, which takes in all the meaningful XML comments you’ve added, and produces documentation in one of a number of common formats.
The big problem when going over to doing work in VB.Net, is that although the development environment can make use of the XML comment files, out of the box there is no way to produce them. Luckily, there is a handy little tool called VBCommenter, that provides the missing feature.
I grabbed a copy of VBCommenter when I started off with my current VB.Net project, and it’s worked pretty well, indeed with the add-in in place it has been pretty much the same as working with C#. That was until today.
This afternoon I had one of those afternoons where things fairly obviously weren’t working, but I was left scratching my head as to why. I’d added comments to an assembly, run the project through NDoc and it was resolutely not picking up my comments. Indeed on one particular class there was just a single method that was failing to appear. Looking at the XML files produced by VBCommenter I couldn’t spot any obvious problems in the sections of the file that were not being picked up. I even got to the point of reinstalling both NDoc and VBCommenter, all to no avail.
Typically the source of the problem turned out to be two quite trivial problems. The single method that was failing was caused by a problem in the what VBCommenter produces for arrays. The method in question was taking an array of strings as a parameter, which in C# would be declared as ‘System.String[]‘, and in VB.Net is ‘System.String()’ – note the different brackets. VBCommenter wrote the VB.Net version to the XML file, whilst NDoc was looking for the C# version. The other problem was as a result of a change I had made last week. I had replaced a property with a method call, to solve a bug, and had temporarily commented out the property whilst I tested the new method. However, looking through the XML file produced I spotted that rather than ignore the commented out property, VBCommenter had written the lines out to the XML file, complete with comment characters. Simply removing the commented out method resulted in the documentation being produced as expected.
Interestingly when having found the problem I ran the file with the comment in it through XMLSpy it did come back as being a badly formed file – however NDoc will quite happily process it without raising any sort of complaint, or even dropping a hint that there might be a problem!
