<summary> (Руководство по программированию на C#)

Статья
06/10/2015

<summary>description</summary>

Параметры

description
Сводка объекта.

Заметки

Тег <summary> следует использовать для описания типа или члена типа. Чтобы добавить дополнительную информацию в описание типа, используйте <remarks>. Чтобы включить средства документации, такие как Sandcastle, для создания внутренних гиперссылок на страницы документации для элементов кода, используйте атрибут cref Attribute.

Текст в теге <summary> является единственным источником сведений о типе для технологии IntelliSense и также отображается в Object Browser Window.

Чтобы обработать и сохранить комментарии документации в файл, при компиляции необходимо использовать параметр /doc. Для создания конечной документации на основе созданного компилятором файла можно создать пользовательское средство или использовать такое средство, как 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()
    {
    }
}

В предыдущем примере получаются следующие XML-файл.

<?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>

В следующем примере показано, как создать ссылку cref на универсальный тип.

// 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> { }

В предыдущем примере получаются следующие XML-файл.

<?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#

Поделиться через