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

This was asked and answered at http://stackoverflow.com/questions/532166/c-how-to-reference-generic-classes-and-methods-in-xml-documentation — kaj, Feb 23 '12 at 12:21
@KAJ since OP updated and corrected a copy/paste error I agree and voted to close as duplicate. — Filburt, Feb 23 '12 at 12:30

score 7 · Accepted Answer · answered Feb 23 '12 at 12:18

7

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.

answered Feb 23 '12 at 12:18

Rob Levine

40,328
13
85
111

1

yes - you can do that as well - although it makes the code documentation itself less readable IMHO. – Rob Levine Feb 23 '12 at 12:23

AssembledGhost · Answer 2 · 2012-02-23T12:27:20.623

5

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.

edited Feb 23 '12 at 12:27

answered Feb 23 '12 at 12:19

AssembledGhost

151
4

Sorry, that was a copy/paste issue. Just added the closing tag for remarks. – GETah Feb 23 '12 at 12:23

score 3 · Answer 3 · answered Feb 23 '12 at 12:28

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>
{
    ....
}

Thanks for the quick response. I will go for using {} instead of < and < — GETah, Feb 23 '12 at 12:34

score 2 · Answer 4 · answered Feb 23 '12 at 12:18

2

Your <remarks> are never closed.

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

answered Feb 23 '12 at 12:18

Filburt

17,626
12
64
115

Sorry, that was a copy/paste issue. Just added the closing tag for remarks. – GETah Feb 23 '12 at 12:24
In that case KAJ is right and using curly braces will fix your issue. – Filburt Feb 23 '12 at 12:29

Generics in XML documentation issue

4 Answers4

Linked