Рекомендуемые теги для комментариев документации

Компилятор C# может обрабатывать комментарии документации в коде в XML-файл. Обработка XML-файла для создания документации является деталью, которая должна быть учтена при реализации в узле.

Теги обрабатываются в конструкциях кода, таких как типы и члены типов.

Примечание.

Комментарии документации не могут быть применены к пространству имен.

Компилятор обрабатывает любой тег, который является допустимым тегом XML.

 

How to: Use the XML Documentation Features

The following sample provides a basic overview of a type that has been documented.

Example

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

Использование XML-документации

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

Пример

ß------

 

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

 

ß-----

Compiling the Code

To compile the example, type the following command line:

csc XMLsample.cs /doc:XMLsample.xml

This will create the XML file XMLsample.xml, which you can view in your browser or by using the TYPE command.

Robust Programming

XML documentation starts with ///. When you create a new project, the wizards put some starter /// lines in for you. The processing of these comments has some restrictions:

· The documentation must be well-formed XML. If the XML is not well-formed, a warning is generated and the documentation file will contain a comment that says that an error was encountered.

· Developers are free to create their own set of tags. There is a recommended set of tags (see the Further Reading section). Some of the recommended tags have special meanings:

· The <param> tag is used to describe parameters. If used, the compiler will verify that the parameter exists and that all parameters are described in the documentation. If the verification failed, the compiler issues a warning.

· The cref attribute can be attached to any tag to provide a reference to a code element. The compiler will verify that this code element exists. If the verification failed, the compiler issues a warning. The compiler respects any using statements when it looks for a type described in the cref attribute.

· The <summary> tag is used by IntelliSense inside Visual Studio to display additional information about a type or member.

Note:

The XML file does not provide full information about the type and members (for example, it does not contain any type information). To get full information about a type or member, the documentation file must be used together with reflection on the actual type or member.

 

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

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

csc XMLsample.cs /doc:XMLsample.xml

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

Надежное программирование

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

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

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

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

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

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

Примечание.

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

 

Application Domains

Application domains provide a flexible and secure method of isolating running applications.

Application domains are usually created and manipulated by run-time hosts. Occasionally, you may want your application to programmatically interact with your application domains, for example, to unload a component without having to stop your application from running.

Application domains aid security, separating applications from each other and each other's data. A single process can run several application domains, with the same level of isolation that would exist in separate processes. Running multiple applications within a single process increases server scalability.

In the following code example, you create a new application domain and then load and execute a previously built assembly, HelloWorld.exe, that is stored on drive C.