how to cref generic classes w/ generic params like List<T>.RemoveAll(Predicate<T>) ?

Topics: User Forum
Mar 24, 2009 at 3:47 PM

currently I'm puzzled by trying to create a cref link to System.Collections.Generic.List<T>.RemoveAll(System.Predicate<T>) in the XML-tags for documenting my source code.
References to plain generics are OK. However, trouble comes in with generic params:

        /// <para><see cref="T:System.Predicate`1"/></para>
        /// <para><see cref="T:System.Collections.Generic.List`1"/></para>
        /// <para><see cref="M:System.Collections.Generic.List`1.Clear"/></para>

are working as expected whereas

        /// <para><see cref="M:System.Collections.Generic.List`1.RemoveAll(T:System.Predicate(`0))"/></para>
        /// <para><see cref="M:System.Collections.Generic.List`1.RemoveAll(T:System.Predicate`1)"/></para>
        /// <para><see cref="M:System.Collections.Generic.List`1.RemoveAll{T:System.Predicate`1}"/></para>

are not.
I'm using VS2008 C# and the Sandcastle HFB 1.8.01 .
Anybody having any ideas or hints how to get a valid link being generated?

TIA and regards

Mar 25, 2009 at 7:36 PM
Use curly braces around the generic type parameters like this:

/// <see cref="Predicate{T}"/>
/// <see cref="List{T}"/>
/// <see cref="List{T}.Clear()"/>
/// <see cref="List{T}.RemoveAll(Predicate{T})"/>

Mar 26, 2009 at 7:53 AM

thanks for the straight solution to this issue.
Just for curiosity: what is the semantical difference between

        /// <see cref="M:System.Collections.Generic.List`1.Clear"/>


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

They both create the same markup in the documentation but only the second form gives you an idea how to derive the correct syntax for generic methods with generic params.

Mar 26, 2009 at 7:41 PM
The end result is the same.  The first form is what the compiler ultimately outputs for the reference.  Since you can't use angle brackets to denote the generic parameters because it would look like an unclosed XML tag, I'm assuming the compiler writers chose to use curly braces as a substitute.  That way you get to use the more intuitive syntax when writing the comments.  The compiler interprets the syntax and generates the correct mangled name for the ID in the comments file which matches the signature of the method in the assembly metadata.