Showing generic class eg Table in xml comm

2020-02-13 08:35发布

问题:

I know this maybe a basic question but I just can't seem to find the answer anywhere.

I have a class like this

Table<T>
{}

then I have some code that uses the above class that I would like to comment I would like to be able to do something like:

/// <summary>
/// blah blah blah Table<String>
/// </summary>

But I can't use the angle bracket in the comment as it thinks it's a tag and when the help shows up it just has an error about no end tag for .

How do I show generic classes in comments in Visual Studio.

回答1:

You need to use XML entities (sort of escape sequences): &lt; for < and &gt; for >. Intellisense will display < as and > correctly.

EDIT: Here's a cheat sheet listing of all of the XML entities:

&lt;   for <
&gt;   for >
&amp;  for &
&quot; for "
&apos; for '


回答2:

try using an &lt; instead of a <



回答3:

The problem with &lt; is that it looks ugly and is hard to read in comments. I use the following: GenericThing≪T,U≫. That's not two angle bracket characters but a single character. It looks OK in Intellisense and when reading the comments. If you use <summary> etc to output documentation then it's not strictly correct, but it works for me.



回答4:

If you place it in a cref element, you can instead use { and }.
That is, inside the summary, instead of Table<string>, you put <cref="Table{string}"/>

From XML Documentation Comments:

To refer to generic identifiers in code reference ... As a special case, the compiler parses the braces [in crefs] as angle brackets to make the documentation comment less cumbersome to author when referring to generic identifiers.

For more info about cref, see cref Attribute:

The cref attribute in an XML documentation tag means "code reference." It specifies that the inner text of the tag is a code element, such as a type, method, or property. Documentation tools like DocFX and Sandcastle use the cref attributes to automatically generate hyperlinks to the page where the type or member is documented.


NOTE: For convenience, I sometimes use {} instead of <> (in a summary comment) even if NOT part of a cref.