Generics in XML documentation issue

问题

I am trying to include a code snippet in my class XML documentation but the compiler complaining that an xml element is not closed! Here is what I am trying to achieve

/// <summary>
/// Method documentation here...
/// </summary>
/// <remarks>
/// <para>
/// This class should be used as follow:
/// <br/>
/// ************** PROBLEM IN NEXT LINE ********************
/// <c> MyClass class = new MyClass<String>(); </c>
/// </para>
/// </remarks>
public class MyClass<T>{
....
}

I tried to replace the code snippet by /// <c> MyClass class = new MyClass{String}(); </c>

Any one has experienced this before?

Thanks for your help

回答1:

In xml documentation, you have to replace the triangular braces with curly braces:

 /// <summary>
 /// Calls <see cref="DoSomething{T}"/>.
 /// </summary>
 public void CallsDoSomething()
 {

 }

 public void DoSomething<T>()
 {

 }

The reason you end up forced to do this, it because it genuinely isn't well formed xml if you allow triangular braces outside of element markup.

The replace you tried is correct.

回答2:

You didn't close the Remarks element in the 4th line, it might be complaining about that, just at the wrong line number.

Also, with examples containing generics, it picks up List<string> as the text literal List followed by an unclosed string XML element. The easiest way around this is to do List &lt;string&gr; which when parsed produces List<string> without being an XML element.

The C# compiler team added { and } as replacements for that, so you can just do List{string} and it will be processed into <>'s.

回答3:

A couple of things:

Escape your < and > characters by replacing them with < and >.
Close your XML <remarks> section with a </remarks>
When you do decided to reference a generic in a tag (i.e. <see ... />, <seealso ... />, etc.) then you would do so like the following: <see cref="SomeMethod{T}(T value)" />. Never specify a concrete type in the reference (that is, don't do <see cref="SomeMethod{String}(String value)" />).

Here is a fixed version of your XML Comments:

/// <summary>
/// Method documentation here...
/// </summary>
/// <remarks>
/// <note type="implementsinfo">
///     <para>This class should be used as follow:</para>
///     <para><c>MyClass class = new MyClass&lt;string&lt;();</c></para>
/// </note>
/// </remarks>
public class MyClass<T>
{
    ....
}

回答4:

Your <remarks> are never closed.

Replacing the angular braces like you already tried is also needed.

来源：https://stackoverflow.com/questions/9412865/generics-in-xml-documentation-issue

标签

xml-documentation