cref Attribute (C# Programming Guide)
The cref attribute in an XML documentation tag means "code reference." It specifies that the inner text of the tag is a code element, such as a type, method, or property. Documentation tools like Sandcastle use the cref attributes to automatically generate hyperlinks to the page where the type or member is documented.
Example
The following example shows a cref attribute used in a <see> tag.
// Save this file as CRefTest.cs
// Compile with: csc CRefTest.cs /doc:Results.xml
namespace TestNamespace
{
/// <summary>
/// TestClass contains two cref examples.
/// </summary>
public class TestClass
{
/// <summary>
/// The GetZero method.
/// </summary>
/// <example>
/// This sample shows how to call the <see cref="GetZero"/> method.
/// <code>
/// class TestClass
/// {
/// static int Main()
/// {
/// return GetZero();
/// }
/// }
/// </code>
/// </example>
public static int GetZero()
{
return 0;
}
/// <summary>
/// The GetGenericValue method.
/// </summary>
/// <remarks>
/// This sample shows how to specify the <see cref="GetGenericValue"/> method as a cref attribute.
/// </remarks>
public static T GetGenericValue<T>(T para)
{
return para;
}
static int Main()
{
return GetZero();
}
}
/// <summary>
/// GenericClass.
/// </summary>
/// <remarks>
/// This example shows how to specify the <see cref="GenericClass{T}"/> type as a cref attribute.
/// </remarks>
class GenericClass<T>
{
// Fields and members.
}
}
When compiled, the program produces the following XML file. Note that the first cref attribute has been transformed by the compiler to "M:TestNamespace.TestClass.GetZero". The "M:" prefix means "method" and is a convention that is recognized by documentation tools such as Sandcastle. For a complete list of prefixes, see Processing the XML File (C# Programming Guide).
<?xml version="1.0"?>
<doc>
<assembly>
<name>CRefTest</name>
</assembly>
<members>
<member name="T:TestNamespace.TestClass">
<summary>
TestClass contains two cref examples.
</summary>
</member>
<member name="M:TestNamespace.TestClass.GetZero">
<summary>
The GetZero method.
</summary>
<example> This sample shows how to call the <see cref="M:TestNamespace.TestClass.GetZero"/> method.
<code>
class TestClass
{
static int Main()
{
return GetZero();
}
}
</code>
</example>
</member>
<member name="M:TestNamespace.TestClass.GetGenericValue``1(``0)">
<summary>
The GetGenericValue method.
</summary>
<remarks>
This sample shows how to specify the <see cref="M:TestNamespace.TestClass.GetGenericValue``1(``0)"/> method as a cref attribute.
</remarks>
</member>
<member name="T:TestNamespace.GenericClass`1">
<summary>
GenericClass.
</summary>
<remarks>
This example shows how to specify the <see cref="T:TestNamespace.GenericClass`1"/> type as a cref attribute.
</remarks>
</member>
</members>
</doc>
See Also
Reference
XML Documentation Comments (C# Programming Guide)
Recommended Tags for Documentation Comments (C# Programming Guide)
Change History
Date |
History |
Reason |
---|---|---|
June 2010 |
Revised the example. |
Customer feedback. |