Export (0) Print
Expand All
1 out of 1 rated this helpful - Rate this topic

<summary> (C# Programming Guide)

<summary>description</summary>
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>
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.