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

В Visual C# можно создавать документацию для кода путем включения XML-элементов в специальные поля комментариев (начинающиеся с трех символов косой черты) в исходном коде непосредственно перед блоком кода, к которому относятся комментарии. Например:In Visual C# you can create documentation for your code by including XML elements in special comment fields (indicated by triple slashes) in the source code directly before the code block to which the comments refer, for example:

/// <summary>  
///  This class performs an important function.  
/// </summary>  
public class MyClass{}  

При выполнении компиляции с параметром /doc компилятор осуществляет поиск всех тегов XML в исходном коде и создает XML-файл документации.When you compile with the /doc option, the compiler will search for all XML tags in the source code and create an XML documentation file. Для получения окончательной документации на основе созданного компилятором файла можно создать пользовательский инструмент или использовать инструмент Sandcastle.To create the final documentation based on the compiler-generated file, you can create a custom tool or use a tool such as Sandcastle.

Для ссылки на XML-элементы (например, если функция обрабатывает определенные XML-элементы, которые требуется включить в комментарии XML-документации) можно использовать стандартный механизм заключения в скобки (< и >).To refer to XML elements (for example, your function processes specific XML elements that you want to describe in an XML documentation comment), you can use the standard quoting mechanism (< and >). Для ссылки на универсальные идентификаторы в элементах ссылок кода (cref) можно использовать escape-символы (например, cref="List&lt;T&gt;") или фигурные скобки (cref="List{T}").To refer to generic identifiers in code reference (cref) elements, you can use either the escape characters (for example, cref="List&lt;T&gt;") or braces (cref="List{T}"). В особом случае компилятор анализирует фигурные скобки, как угловые, чтобы при ссылке на универсальные идентификаторы сделать комментарий документации менее громоздким.As a special case, the compiler parses the braces as angle brackets to make the documentation comment less cumbersome to author when referring to generic identifiers.

Примечание

Комментарии XML-документации не являются метаданными. Они не включаются в скомпилированную сборку, и поэтому не доступны посредством отражения.The XML documentation comments are not metadata; they are not included in the compiled assembly and therefore they are not accessible through reflection.

В этом разделеIn This Section

Дополнительные сведения:For more information, see:

Спецификация языка C#C# Language Specification

Дополнительные сведения см. в спецификации языка C#. Спецификация языка является предписывающим источником информации о синтаксисе и использовании языка C#.

См. такжеSee Also

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