I have found a bug that only occurs under very specific circumstances as far as I can tell. My setup is Visual Studio 2005 with Visual SourceSafe 2005 as my source control. What I am attempting to do is use XML documentation (I am using C#) to document a class I have written.
I start off with a
summary section, followed by a
remarks section and everything is fine. Next I wanted to add an
example section to show how the class must be configured in the Web.config. That seems harmless enough, so I add the following documentation:
<example> <configuration> <system.web> <httpModules> <add name="WSAuth" type="MyWS.Auth" /> </httpModules> </system.web> </configuration> </example>
The problem with this is twofold. First, Intellisense is trying to identify each of the XML elements in the
example element. Second, when this is documented using Sandcastle, it will not show up correctly.
The solution to this problem is adding
]]> around the example code. This stops Intellisense from attempting to identify the elements, and it will now show up in the help documentation. But instead of being nicely styled in the help document so that it is easy to read, all whitespace is stripped from the help file and the example ends up crunched together like this:
<example><configuration><system.web><httpModules> <add name="WSAuth" type="MyWS.Auth" /></httpModules></system.web> </configuration></example>
Now I know from previous experience that if I add a
code element around the example and CDATA, it will honor the whitespace in the help document and color-code it as well. This is just what I want.
Here is where the bug is introduced. When I try to get my cursor focused on the correct spot in the code using the mouse, Visual Studio hangs. There is nothing that can be done until it finally throws an error (after 10 minutes or so) complaining about a runtime problem, upon which time it promptly crashes. Here is what is says:
I have no idea what is causing this. I do know that if you type <code> and </code> somewhere else and then cut-and-paste you can get around the problem. But it could still hang even while attempting this. I would love to hear anyone’s idea solution to this problem.