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 stackoverflow.com/questions/532166/… — kaj
– kaj, Commented Feb 23, 2012 at 12:21
@KAJ since OP updated and corrected a copy/paste error I agree and voted to close as duplicate. — Filburt
– Filburt, Commented Feb 23, 2012 at 12:30

Rob Levine · Accepted Answer · 2012-02-23 12:18:03Z

8

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, 2012 at 12:18

Rob Levine

41.5k13 gold badges88 silver badges114 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Rob Levine Over a year ago

yes - you can do that as well - although it makes the code documentation itself less readable IMHO.

AssembledGhost · Accepted Answer · 2012-02-23 12:27:20Z

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, 2012 at 12:27

answered Feb 23, 2012 at 12:19

AssembledGhost

1514 bronze badges

1 Comment

GETah Over a year ago

Sorry, that was a copy/paste issue. Just added the closing tag for remarks.

myermian · Accepted Answer · 2012-02-23 12:28:08Z

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

answered Feb 23, 2012 at 12:28

myermian

32.6k26 gold badges135 silver badges222 bronze badges

1 Comment

GETah Over a year ago

Thanks for the quick response. I will go for using {} instead of < and <

Filburt · Accepted Answer · 2012-02-23 12:18:43Z

2

Your <remarks> are never closed.

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

answered Feb 23, 2012 at 12:18

Filburt

18.1k14 gold badges106 silver badges167 bronze badges

2 Comments

GETah Over a year ago

Sorry, that was a copy/paste issue. Just added the closing tag for remarks.

Filburt Over a year ago

In that case KAJ is right and using curly braces will fix your issue.

Collectives™ on Stack Overflow

Generics in XML documentation issue

4 Answers 4

1 Comment

1 Comment

1 Comment

2 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

4 Answers 4

1 Comment

1 Comment

1 Comment

2 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related