---- Reported by brian.nickel@gmail.com 2007-07-04 07:36:42 MST ----

I'm trying to reference a generic type in XML comments via <see
cref="ListBase&lt;string>" />

But I get this warning:
XML comment on `TagLib.StringCollection' has syntactically incorrect cref
attribute `ListBase<T>'(CS1584)

According to http://blogs.msdn.com/ansonh/archive/2006/09/11/750056.aspx,
both "ListBase&lt;string>" and "ListBase{string}" should both work.



---- Additional Comments From atsushi@ximian.com 2007-07-18 06:36:00 MST ----

The actual csc behavior is that
  <see
cref="ListBase&lt;string>" />
does not work, while
  <see
cref="T:ListBase&lt;string>" />
works. Actually
  <see
cref="T:#$%>" />
works i.e. nothing is checked when T: (or whatever x:) is specified.



---- Additional Comments From atsushi@ximian.com 2007-07-18 06:45:38 MST ----

Fixed in svn.



---- Additional Comments From brian.nickel@gmail.com 2007-08-26 20:23:41 MST ----

I'm still having trouble compiling with: ListBase{string} and
ListBase&lt;string&gt;

According to the C# 3.0 (and I would assume 2.0) specification:

The cref attribute can be attached to any tag to provide a reference
to a code element. The documentation generator must verify that this
code element exists. If the verification fails, the documentation
generator issues a warning. When looking for a name described in a
cref attribute, the documentation generator must respect namespace
visibility according to using statements appearing within the source
code. For code elements that are generic, the normal generic syntax
(ie “List<T>”) cannot be used because it produces invalid XML. Braces
can be used instead of brackets (ie “List{T}”), or the XML escape
syntax can be used (ie “List&lt;T&gt;”).



---- Additional Comments From atsushi@ximian.com 2007-08-27 00:14:20 MST ----

Annex E. is just an informative section that we do not have to follow,
so it is not a bug. I already wrote that without 'T:' it won't work
(it is about csc. The msdn blog post or your interpretation of it is
wrong).



---- Additional Comments From brian.nickel@gmail.com 2007-08-27 04:38:50 MST ----

Okay, I did a bit of testing on this, and it appears that csc has the
following behavior. cref="IList{System.String}" == ERROR,
cref="IList{T}" == SUCCESS. If the bad CREF is encountered, it will
emit two warnings, CS1574 and CS1658.

The following shows the difference between csc and gmcs behavior.

Comment Line: /// <returns>A <see cref="IList&lt;System.String&gt;"
/>.</returns>
csc result:   CS1574 & CS1658

gmcs result:  CS1584
csc output:   <returns>A <see
cref="!:IList&lt;System.String&gt;"/>.</returns>
gmcs output:  <returns>A <see cref="!:IList&lt;System.String&gt;"
/>.</returns>

Comment Line: /// <returns>A <see cref="IList&lt;Foobar&gt;" />.</returns>
csc result:   Success
gmcs result:  CS1584
csc output:   <returns>A <see
cref="T:System.Collections.Generic.IList`1"/>.</returns>
gmcs output:  <returns>A <see cref="!:IList&lt;Foobar&gt;" />.</returns>

Comment Line: /// <returns>A <see cref="IList{System.String}"
/>.</returns>
csc result:   CS1574 & CS1658

gmcs result:  CS1584
csc output:   <returns>A <see
cref="!:IList&lt;System.String&gt;"/>.</returns>
gmcs output:  <returns>A <see cref="!:IList{System.String}" />.</returns>

Comment Line: /// <returns>A <see cref="IList{Foobar}" />.</returns>
csc result:   Success
gmcs result:  CS1584
csc output:   <returns>A <see
cref="T:System.Collections.Generic.IList`1"/>.</returns>
gmcs output:  <returns>A <see cref="!:IList{Foobar}" />.</returns>


Unknown operating system unknown. Setting to default OS "Other".