Generics in XML documentation issue

Question

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

Answer 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.

Answer 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 <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.

Answer 3

A couple of things:

1. Escape your < and > characters by replacing them with < and >.
2. Close your XML <remarks> section with a </remarks>
3. 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>
{
    ....
}