Практическое руководство. Использование XML-документации (Руководство по программированию в C#)

Обновлен: Ноябрь 2007

В следующем примере приводятся общие сведения о документированном типе.

Пример

// compile with: /doc:DocFileName.xml 

/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member 
/// through the remarks tag</remarks>
public class TestClass
{
    /// <summary>
    /// Store for the name property</summary>
    private string _name = null;

    /// <summary>
    /// The class constructor. </summary>
    public TestClass()
    {
        // TODO: Add Constructor Logic here
    }

    /// <summary>
    /// Name property </summary>
    /// <value>
    /// A value tag is used to describe the property value</value>
    public string Name
    {
        get
        {
            if (_name == null)
            {
                throw new System.Exception("Name is null");
            }
            return _name;
        }
    }

    /// <summary>
    /// Description for SomeMethod.</summary>
    /// <param name="s"> Parameter description for s goes here</param>
    /// <seealso cref="System.String">
    /// You can use the cref attribute on any tag to reference a type or member 
    /// and the compiler will check that the reference exists. </seealso>
    public void SomeMethod(string s)
    {
    }

    /// <summary>
    /// Some other method. </summary>
    /// <returns>
    /// Return results are described through the returns tag.</returns>
    /// <seealso cref="SomeMethod(string)">
    /// Notice the use of the cref attribute to reference a specific method </seealso>
    public int SomeOtherMethod()
    {
        return 0;
    }

    /// <summary>
    /// The entry point for the application.
    /// </summary>
    /// <param name="args"> A list of command line arguments</param>
    static int Main(System.String[] args)
    {
        // TODO: Add code to start application here
        return 0;
    }
}

// This .xml file was generated with the previous code sample.
<?xml version="1.0"?>
<doc>
    <assembly>
        <name>xmlsample</name>
    </assembly>
    <members>
        <member name="T:SomeClass">
            <summary>
            Class level summary documentation goes here.</summary>
            <remarks>
            Longer comments can be associated with a type or member 
            through the remarks tag</remarks>
        </member>
        <member name="F:SomeClass.m_Name">
            <summary>
            Store for the name property</summary>
        </member>
        <member name="M:SomeClass.#ctor">
            <summary>The class constructor.</summary> 
        </member>
        <member name="M:SomeClass.SomeMethod(System.String)">
            <summary>
            Description for SomeMethod.</summary>
            <param name="s"> Parameter description for s goes here</param>
            <seealso cref="T:System.String">
            You can use the cref attribute on any tag to reference a type or member 
            and the compiler will check that the reference exists. </seealso>
        </member>
        <member name="M:SomeClass.SomeOtherMethod">
            <summary>
            Some other method. </summary>
            <returns>
            Return results are described through the returns tag.</returns>
            <seealso cref="M:SomeClass.SomeMethod(System.String)">
            Notice the use of the cref attribute to reference a specific method </seealso>
        </member>
        <member name="M:SomeClass.Main(System.String[])">
            <summary>
            The entry point for the application.
            </summary>
            <param name="args"> A list of command line arguments</param>
        </member>
        <member name="P:SomeClass.Name">
            <summary>
            Name property </summary>
            <value>
            A value tag is used to describe the property value</value>
        </member>
    </members>
</doc>

Компиляция кода

Чтобы скомпилировать пример, введите следующую команду из командной строки:

csc XMLsample.cs /doc:XMLsample.xml

При этом создается XML-файл XMLsample.xml, который можно просмотреть в обозревателе или с помощью команды TYPE.

Отказоустойчивость

XML–документация начинается с ///. При создании нового проекта мастера добавляют некоторые начальные строки ///. Обработка этих комментариев имеет некоторые ограничения:

• Документация должна представлять собой XML с правильным форматом. Если формат XML неверен, то выдается предупреждение, и файл документации будет содержать комментарий о том, что произошла ошибка.

• Разработчики могут создавать свои собственные наборы тегов. Здесь представлен рекомендуемый набор тегов (см. раздел "Дополнительные сведения"). Некоторые рекомендуемые теги имеют специальное значение.

  • Тег <param> используется для описания параметров. При его использовании компилятор должен убедиться в том, что параметр существует, и что все параметры описаны в документации. При сбое проверки компилятор выдает предупреждение.

  • Атрибут cref может быть вложен в любой тег для предоставления ссылки на элемент кода. Компилятор проверит наличие этого элемента кода. При сбое проверки компилятор выдает предупреждение. Компилятор учитывает любые операторы using при поиске типа, описанного в атрибуте cref.

  • Тег <summary> используется технологией IntelliSense в Visual Studio для отображения дополнительных сведений о типе или члене.

    Примечание.
    Файл XML не содержит полную информацию о типе и членах (например, он не содержит никаких сведений о типе). Чтобы получить полную информацию о типе или члене, необходимо использовать файл документации вместе с отражением на текущий тип или член.

См. также

Задачи

Пример XML-документации

Основные понятия

Руководство по программированию в C#

Ссылки

/doc (комментарии документации процесса) (параметры компилятора C#)

Комментарии XML-документации (Руководство по программированию в C#)