Possible bug in XML comments tag creation?  
Author Message

PostPosted: Visual Studio Code Analysis and Code Metrics, Possible bug in XML comments tag creation? Top


I've been creating a few rules to validate the presence of XML comments in my code for methods, some members, classes, etc. A few times in the past, I noticed that some functions would show with comments and some within the same file with comments as well in the code, would not be detected by FxCop. By this I mean, the comments are present in the actual XML file but FxCop doesn't detect them. I ran my rule in debug mode and noticed that the Documentation node was indeed null. Surprisingly, for other functions in the same library and file, the comments were detected properly.

After looking into it a bit more, I noticed a pattern that seems to explain this miss. When running in debug, I noticed that the "DocumentationID" of the missing nodes was actually different then the one found in the XML file. Furthermore, the only times when this happened was when a structure or encapsulated class was used. The difference in the tag was very simple and consisted in a "+" (from FxCop) replacing a "." (in the XML file).

For example... If I have a class named Car with classes declared from within it such as Wheel and Motor as well as a structure named Seat also declared within it... So, given that, any comment that is writte within the classes Wheel or Motor, or within the structure Seat, would not be found by FxCop as it would build a key of the form "...Car+Wheel.Radius" for the Radius member whereas the XML file uses a key of the form "...Car.Wheel.Radius". When FxCop looks for the documentionID, it never finds it and assumes no documention is present.

The same would be true for a function within the class Car that would take in as a parameter an instance of any of those 2 classes or 1 structure. For example, if a function SetWheel(Wheel myWheel) existed and its documentation included the description of the myWheel parameter, FxCop would not be able to find it once again based on a wrong key.

Hopefully this makes sense... lol

So my question is, is this a known bug Or am I doing something wrong here or maybe do I have to set a parameter Thanks a lot!!

Visual Studio Team System3  
David M. Kean - MSFT

PostPosted: Visual Studio Code Analysis and Code Metrics, Possible bug in XML comments tag creation? Top

Sorry for the late reply, we've been working **** finishing up our feature work for the next version of Visual Studio and we seemed to have missed this one.

Unfortunately, in the next version of FxCop/Visual Studio, in an effort to clean up our API and reduce our test matrix, the XML comments support has been ripped. I will take this post as a vote add this support back in a future version.