TypeParam and TypeParamRef question

This is probably a very simple question, but since I know nothing about Generics, I am not sure of what is a <typeparam> and what is a <typeparamref>.

For this example (from the MSDN documentation):

Code Snippet
/// comment for class
public class TestClass
{
/// <summary>
/// Creates a new array of arbitrary type <typeparamref name="T"/>
/// </summary>
/// <typeparam name="T">The element type of the array</typeparam>
public static T[] mkArray(int n)
{ return new T[n];}
}

Which "T" does the <typeparam> refer to and which "T" does the <typeparamref> refer to?

And for this example (from the Sandcastle Test.cs file):

Code Snippet

/// <summary>
/// <para><typeparam name="T">The element type to swap</typeparam></para>
/// <para>Swap data of type <typeparam name="T"></para>
/// </summary>
/// <typeparamref name="T"/>
public void Swap<T>(ref T lhs, ref T rhs)
{
T temp;
temp = lhs;
lhs = rhs;
rhs = temp;
}

Which "T" does the <typeparam> refer to and which "T" does the <typeparamref> refer to?

Do the "ref T lhs" and "ref T rhs" values become

<param name="lhs">description</param>

<param name="rhs">description</param>

Thanks,

Eric

[2167 byte] By [Dynicity] at [2008-1-7]
# 1
Hi Eric,

The second example is not correct usage of typeparam and typeparamref. They should be reversed, as in the first example.

In the first example, they refer to the same generic argument named, "T". There is only one.

If you want to provide documentation for the lhs parameter, for example, you'd use:

<summary>...</summary>
<param name="lhs">Some docs.</param>

If you wanted to "refer" to this parameter from within the summary, you'd use:

<summary>
The first parameter is <paramref name="lhs" />.
</summary>


The typeparam and typeparamref elements are similar, but are used for generic arguments (not method arguments).

The T in Swap<T> is a generic argument.

- Dave

DaveSexton at 2007-10-2 > top of Msdn Tech,Visual Studio,Developer Documentation and Help System...
# 2

Dave,

Thanks for the explanation.

Eric

Dynicity at 2007-10-2 > top of Msdn Tech,Visual Studio,Developer Documentation and Help System...

Visual Studio

Site Classified