Link to List(Of T)

Topics: Developer Forum, User Forum
Nov 28, 2008 at 12:41 PM


I am trying to create a link to the MS documentation on List topics, inside my <summary> tags. The tag I have now is that:

<![CDATA[<see cref="List(Of T)" />]]>

But it seems to not work. I tried some changes on the above syntax but without sucess. How do I correctly write a link for a list with arguments?


Nov 28, 2008 at 4:24 PM
You need to use curly braces around the generic arguments rather than the language-specific syntax.  For example:

/// For information on lists, see <see cref="List{T}" />.
/// For information on dictionaries, see <see cref="Dictionary{TKey, TValue}" />.

If using VB.NET, the compiler doesn't always fully qualify the references you may need to do it manually:

''' For information on lists, see <see cref="System.Collections.Generic.List{T}" />.
''' For information on dictionaries, see <see cref="System.Collections.Generic.Dictionary{TKey, TValue}" />.

Dec 1, 2008 at 11:16 AM
Hi Eric !

I am using VB.NET and tried the following declaration:

<see cref="System.Collections.Generic.List{T}" />

It didn't work. I receive this warning:

XML comment has a tag with a 'cref' attribute 'System.Collections.Generic.List{T}' that could not be resolved. XML comment will be ignored.

Is it some kind of limitation of the VB.NET compiler or are there other syntaxes?

Dec 1, 2008 at 3:22 PM
I forgot that to be fully qualified in VB.NET so that it passes through to the comments file you need to include the prefix ("T:" for types, "M:" for methods, "P:" for properties, etc.).  As such the correct form will be:

''' <see cref="T:System.Collections.Generic.List{T}" />.
''' <see cref="T:System.Collections.Generic.Dictionary{TKey, TValue}" />.

Dec 2, 2008 at 2:42 PM
Hi Eric !

Reallly, adding the prefix removes the warning message and the topic is generated, but without a hyperlink pointing to the documentation. It apears as an static bold text.

Does this work in C#? If it is an issue with the VB.NET compiler I think it is better to remove this entry from the help file.

Dec 2, 2008 at 3:23 PM
Try specifying the number of generic arguments after a back-apostrophe (it's the one under the tilde "~" usually in the upper left of the keyboard):

''' <see cref="T:System.Collections.Generic.List`1" />.
''' <see cref="T:System.Collections.Generic.Dictionary`2" />.

That's how it ends up in the C# comments file.

Dec 2, 2008 at 3:46 PM
Hi Eric,

that worked, thanks.
Is it something that can be automated on the nest release of SHFB or it depends of the VB.NET compiler?

Dec 2, 2008 at 6:35 PM
It's a VB.NET compiler issue.  The compiler needs to be fixed so that it outputs fully qualified names in the proper format.  As I recall, it used to work but VS2005 SP1 broke it and it's still broken in VS2008.  Unfortunately, it isn't something that can be fixed by SHFB like the C++ issue where the compiler adds in extra characters where it shouldn't.