cref Attribute (C# Programming Guide)
Visual Studio 2012
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.
The following example shows cref attributes used in <see> tags.
// Save this file as CRefTest.cs // Compile with: csc CRefTest.cs /doc:Results.xml namespace TestNamespace { /// <summary> /// TestClass contains several cref examples. /// </summary> public class TestClass { /// <summary> /// This sample shows how to specify the <see cref="TestClass"/> constructor as a cref attribute.� /// </summary> public TestClass() { } /// <summary> /// This sample shows how to specify the <see cref="TestClass(int)"/> constructor as a cref attribute.� /// </summary> public TestClass(int value) { } /// <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; } } /// <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. } class Program { static int Main() { return TestClass.GetZero(); } } }
When compiled, the program produces the following XML file. Notice that the cref attribute for the GetZero method, for example, 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 cref examples.
</summary>
</member>
<member name="M:TestNamespace.TestClass.#ctor">
<summary>
This sample shows how to specify the <see cref="T:TestNamespace.TestClass"/> constructor as a cref attribute.
</summary>
</member>
<member name="M:TestNamespace.TestClass.#ctor(System.Int32)">
<summary>
This sample shows how to specify the <see cref="M:TestNamespace.TestClass.#ctor(System.Int32)"/> constructor as a cref attribute.
</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> <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>
