XML in function descriptions doesn't correctly deal with less-than and greater-than
-
As everyone probably knows, in C# (and probably other .NET languages), you can put comments at the top of any class or function in this format (this example is for a function):
/// <summary>super-duper function</summary>
/// <param name="thing">the first parameter</param>
void MyFunction(string thing)The great thing is that C# will automatically use these comments when doing tooltips for auto-complete. I love that. Unfortunately, it seems that auto-complete does not correctly deal with < and > characters when they appear in the XML. For example, if the following XML appears above a function:
/// <summary>If x < y then do something</summary>
...then that is exactly how auto-complete will display the description of the function. It should be doing standard "entity" conversion, e.g. converting < to < and > to > and so on. (You can't just put < into the summary itself, because that's not legal in XML. Try it -- you'll get an error message in the auto-complete tooltip.) For another example of this, try typing "Directory.GetLogicalDrives(" into a C# file, and observe that the tooltip that comes up says:
Retrieves the names of the logical drives on this computer
in the form "<driver letter>:\".Oops. Microsoft, please fix the tooltip code? By the way, Visual Studio's utility for creating HTML documentation (Tools menu, "Build Comment Web Pages..." command) DOES correctly deal with < and > in the XML. Mike Morearty mike@morearty.com http://www.morearty.com
-
As everyone probably knows, in C# (and probably other .NET languages), you can put comments at the top of any class or function in this format (this example is for a function):
/// <summary>super-duper function</summary>
/// <param name="thing">the first parameter</param>
void MyFunction(string thing)The great thing is that C# will automatically use these comments when doing tooltips for auto-complete. I love that. Unfortunately, it seems that auto-complete does not correctly deal with < and > characters when they appear in the XML. For example, if the following XML appears above a function:
/// <summary>If x < y then do something</summary>
...then that is exactly how auto-complete will display the description of the function. It should be doing standard "entity" conversion, e.g. converting < to < and > to > and so on. (You can't just put < into the summary itself, because that's not legal in XML. Try it -- you'll get an error message in the auto-complete tooltip.) For another example of this, try typing "Directory.GetLogicalDrives(" into a C# file, and observe that the tooltip that comes up says:
Retrieves the names of the logical drives on this computer
in the form "<driver letter>:\".Oops. Microsoft, please fix the tooltip code? By the way, Visual Studio's utility for creating HTML documentation (Tools menu, "Build Comment Web Pages..." command) DOES correctly deal with < and > in the XML. Mike Morearty mike@morearty.com http://www.morearty.com
I might have the wrong end of the stick here but I remember back when I first looked into XML that you had to define the "data type" of the XML entity for odd characters and entity-conversion to display properly. Unfortuanatley I am not near my XML book or VS.NET so I cannot remember how to do it, but if you know what I mean then see if defining that data type will help. Not the best solution but it might work :) regards, Paul Watson Bluegrass Cape Town, South Africa Do you Sonork? I do! 100.9903 Stormfront "The greatest thing you will ever learn is to love, and be loved in return" - Moulin Rouge