C# Language
Комментарии к документации XML

замечания

Простая аннотация метода

Комментарии к документации помещаются непосредственно над методом или классом, который они описывают. Они начинаются с трех косых черт /// и позволяют хранить метаинформацию через XML.

/// <summary>
/// Bar method description
/// </summary>
public void Bar()
{ 
        
}

Информация внутри тегов может использоваться Visual Studio и другими инструментами для предоставления таких услуг, как IntelliSense:

См. Также список общих тегов документации Microsoft .

Комментарии к документации по интерфейсу и классу

/// <summary>
/// This interface can do Foo
/// </summary>
public interface ICanDoFoo
{
    // ... 
}

/// <summary>
/// This Bar class implements ICanDoFoo interface
/// </summary>
public class Bar : ICanDoFoo
{
    // ...
}

Результат

Сводка интерфейса

Сводка классов

Комментарий к документации по методу с элементами param и return

/// <summary>
/// Returns the data for the specified ID and timestamp.
/// </summary>
/// <param name="id">The ID for which to get data. </param>
/// <param name="time">The DateTime for which to get data. </param>
/// <returns>A DataClass instance with the result. </returns>
public DataClass GetData(int id, DateTime time)
{
   // ...
}

IntelliSense показывает вам описание для каждого параметра:

Совет. Если Intellisense не отображается в Visual Studio, удалите первую скобку или запятую, а затем введите ее еще раз.

Генерация XML из комментариев к документации

Чтобы создать файл документации XML из комментариев к документации в коде, используйте параметр /doc с компилятором csc.exe C #.

В Visual Studio 2013/2015, в проекте -> Свойства -> Создать -> Вывод , установите флажок в XML documentation file :

Когда вы создадите проект, компилятор будет XMLDocumentation.dll XML-файл с именем, соответствующим имени проекта (например, XMLDocumentation.dll -> XMLDocumentation.xml ).

Когда вы используете сборку в другом проекте, убедитесь, что файл XML находится в том же каталоге, что и ссылка на DLL.

Этот пример:

/// <summary>
/// Data class description
/// </summary>
public class DataClass
{
    /// <summary>
    /// Name property description
    /// </summary>
    public string Name { get; set; }
}


/// <summary>
/// Foo function
/// </summary>
public class Foo
{
    /// <summary>
    /// This method returning some data
    /// </summary>
    /// <param name="id">Id parameter</param>
    /// <param name="time">Time parameter</param>
    /// <returns>Data will be returned</returns>
    public DataClass GetData(int id, DateTime time)
    {
        return new DataClass();
    }
}

Производит этот xml для сборки:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>XMLDocumentation</name>
    </assembly>
    <members>
        <member name="T:XMLDocumentation.DataClass">
            <summary>
            Data class description
            </summary>
        </member>
        <member name="P:XMLDocumentation.DataClass.Name">
            <summary>
            Name property description
            </summary>
        </member>
        <member name="T:XMLDocumentation.Foo">
            <summary>
            Foo function
            </summary>
        </member>
        <member name="M:XMLDocumentation.Foo.GetData(System.Int32,System.DateTime)">
            <summary>
            This method returning some data
            </summary>
            <param name="id">Id parameter</param>
            <param name="time">Time parameter</param>
            <returns>Data will be returned</returns>
        </member>
    </members>
</doc>

Ссылка на другой класс в документации

Тег <see> можно использовать для связи с другим классом. Он содержит член cref который должен содержать имя класса, на который нужно ссылаться. Visual Studio предоставит Intellsense при написании этого тега, и такие ссылки будут обработаны при переименовании ссылочного класса.

/// <summary>
/// You might also want to check out <see cref="SomeOtherClass"/>.
/// </summary>
public class SomeClass
{
}

В всплывающих окнах Visual Studio Intellisense такие ссылки также будут отображаться по цвету в тексте.

Чтобы ссылаться на общий класс, используйте что-то похожее на следующее:

/// <summary>
/// An enhanced version of <see cref="List{T}"/>.
/// </summary>
public class SomeGenericClass<T>
{
}