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

XML–документация предоставляет эффективный способ документирования кода. В данном примере представлены основные общие сведения.

Пример

// If compiling from the command line, compile with: /doc:YourFileName.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 : TestInterface
{
    /// <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;
    }

    public int InterfaceMethod(int n)
    {
        return n * n;
    }

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

/// <summary>
/// Documentation that describes the interface goes here.
/// </summary>
/// <remarks>
/// Details about the interface go here.
/// </remarks>
interface TestInterface
{
    /// <summary>
    /// Documentation that describes the method goes here.
    /// </summary>
    /// <param name="n">
    /// Parameter n requires an integer argument.
    /// </param>
    /// <returns>
    /// The method returns an integer.
    /// </returns>
    int InterfaceMethod(int n);
}

Следующий XML-файл создается в предыдущем примере. Обратите внимание, что комментарии из определения интерфейса включены в класс, реализующий этот интерфейс.

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

Чтобы скомпилировать пример, можно ввести следующее в командной строке: csc XMLsample.cs /doc:XMLsample.xml.

Эта команда создает XML-файл XMLsample.xml, который можно просмотреть в браузере или с помощью текстового процессора.

Иначе в окне Обозреватель решений щелкните правой кнопкой мыши имя проекта и выберите команду Свойства. На вкладке Построение выберите XML-файл документации в разделе Выходные данные и затем введите имя XML-файла.

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

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

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

• Разработчики могут создавать собственные наборы тегов. Однако существует рекомендуемый набор тегов (см. раздел "См. также" в данной теме) со специальными значениями, как описано в следующих примерах:

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

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

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

    Примечание

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

См. также

Ссылки

/doc (параметры компилятора C#)

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

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

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

Журнал изменений

Дата	Журнал	Причина
Апрель 2011	Добавлен интерфейс в пример.	Обратная связь от клиента.