<summary> (C# Programming Guide)

 

Updated: July 20, 2015

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

<summary>description</summary>  

Parameters

description
A summary of the object.

The <summary> tag should be used to describe a type or a type member. Use <remarks> to add supplemental information to a type description. Use the cref Attribute to enable documentation tools such as Sandcastle to create internal hyperlinks to documentation pages for code elements.

The text for the <summary> tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser Window.

Compile with /doc to process documentation comments to a file. To create the final documentation based on the compiler-generated file, you can create a custom tool, or use a tool such as Sandcastle.

    // compile with: /doc:DocFileName.xml 

    /// text for class TestClass
    public class TestClass
    {
        /// <summary>DoWork is a method in the TestClass class.
        /// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>
        /// <seealso cref="TestClass.Main"/>
        /// </summary>
        public static void DoWork(int Int1)
        {
        }

        /// text for Main
        static void Main()
        {
        }
    }

The previous example produces the following XML file.

<?xml version="1.0"?>  
<doc>  
    <assembly>  
        <name>YourNamespace</name>  
    </assembly>  
    <members>  
        <member name="T:DotNetEvents.TestClass">  
            text for class TestClass  
        </member>  
        <member name="M:DotNetEvents.TestClass.DoWork(System.Int32)">  
            <summary>DoWork is a method in the TestClass class.  
            <para>Here's how you could make a second paragraph in a description. <see cref="M:System.Console.WriteLine(System.String)"/> for information about output statements.</para>  
            <seealso cref="M:DotNetEvents.TestClass.Main"/>  
            </summary>  
        </member>  
        <member name="M:DotNetEvents.TestClass.Main">  
            text for Main  
        </member>  
    </members>  
</doc>  

The following example shows how to make a cref reference to a generic type.

    // compile with: /doc:DocFileName.xml 

    // the following cref shows how to specify the reference, such that,
    // the compiler will resolve the reference
    /// <summary cref="C{T}">
    /// </summary>
    class A { }

    // the following cref shows another way to specify the reference, 
    // such that, the compiler will resolve the reference
    // <summary cref="C &lt; T &gt;">

    // the following cref shows how to hard-code the reference
    /// <summary cref="T:C`1">
    /// </summary>
    class B { }

    /// <summary cref="A">
    /// </summary>
    /// <typeparam name="T"></typeparam>
    class C<T> { }

The previous example produces the following XML file.

<?xml version="1.0"?>  
<doc>  
    <assembly>  
        <name>YourNamespace</name>  
    </assembly>  
    <members>  
        <member name="T:ExtensionMethodsDemo1.A">  
            <summary cref="T:ExtensionMethodsDemo1.C`1">  
            </summary>  
        </member>  
        <member name="T:ExtensionMethodsDemo1.B">  
            <summary cref="T:C`1">  
            </summary>  
        </member>  
        <member name="T:ExtensionMethodsDemo1.C`1">  
            <summary cref="T:ExtensionMethodsDemo1.A">  
            </summary>  
            <typeparam name="T"></typeparam>  
        </member>  
    </members>  
</doc>  
  

C# Programming Guide
Recommended Tags for Documentation Comments

Show: