VS XML注释-白红宇

1.<c>

其中：

text 希望将其指示为代码的文本。

备注

<c> 标记为您提供了一种将说明中的文本标记为代码的方法。使用 <code> 将多行指示为代码。

使用 /doc 进行编译可以将文档注释处理到文件中。

示例

// xml_c_tag.cs

// compile with: /doc:xml_c_tag.xml

/// text for class MyClass

public class MyClass

{

/// <summary><c>MyMethod</c> is a method in the <c>MyClass</c> class.

/// </summary>

public static void MyMethod(int Int1)

{

}

/// text for Main

public static void Main ()

{

}

2.<para>

请参见

建议的文档注释标记

<para>content</para>

其中：

content

段落文本。

备注

<para> 标记用于诸如<summary>、<remarks> 或 <returns> 等标记内，使您得以将结构添加到文本中。

使用 /doc 进行编译可以将文档注释处理到文件中。

3. <see>

请参见

建议的文档注释标记

其中：

cref = "member"

对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 member 传递给输出 XML 中的元素名。必须将 member 括在双引号 (" ") 中。

备注

<see> 标记使您得以从文本内指定链接。使用 <seealso> 指示希望在“请参见”一节中出现的文本。

使用 /doc 进行编译可以将文档注释处理到文件中。

4. <code>

请参见

建议的文档注释标记

<code>content</code>

其中：

content

希望将其标记为代码的文本。

备注

<code> 标记为您提供了一种将多行指示为代码的方法。使用 <c> 指示应将说明中的文本标记为代码。

使用 /doc 进行编译可以将文档注释处理到文件中。

5. <param>

请参见

建议的文档注释标记

<param name='name'>description</param>

其中：

name

方法参数名。将此名称用单引号括起来 (' ')。

description

参数说明。

备注

<param> 标记应当用于方法声明的注释中，以描述方法的一个参数。

有关 <param> 标记的文本将显示在智能感知、对象浏览器和代码注释 Web 报表中。

使用 /doc 进行编译可以将文档注释处理到文件中。

示例

// xml_param_tag.cs

// compile with: /doc:xml_param_tag.xml

/// text for class MyClass

public class MyClass

{

/// <param name="Int1">Used to indicate status.</param>

public static void MyMethod(int Int1)

{

}

/// text for Main

public static void Main ()

{

}

6. <seealso>

请参见

建议的文档注释标记

其中：

cref = "member"

备注

<seealso> 标记使您得以指定希望在“请参见”一节中出现的文本。使用 <see> 从文本内指定链接。

使用 /doc 进行编译可以将文档注释处理到文件中。

7. <example>

请参见

建议的文档注释标记

<example>description</example>

其中：

description

代码示例的说明。

备注

使用 <example> 标记可以指定使用方法或其他库成员的示例。一般情况下，这将涉及到 <code> 标记的使用。

使用 /doc 进行编译可以将文档注释处理到文件中

示例

// xml_example_tag.cs

// compile with: /doc:xml_ctag.xml

/// text for class MyClass

public class MyClass

{

/// <summary>

/// The GetZero method.

/// </summary>

/// <example> This sample shows how to call the GetZero method.

/// <code>

/// class MyClass

/// {

/// public static int Main()

/// {

/// return GetZero();

/// }

/// </code>

/// </example>

public static int GetZero()

{

return 0;

}

/// text for Main

public static void Main ()

{

}

8. <paramref>

请参见

建议的文档注释标记

其中：

name

要引用的参数名。将此名称用双引号括起来 (" ")。

备注

<paramref> 标记为您提供了一种指示词为参数的方法。可以处理 XML 文件，从而用某种独特的方法格式化该参数。

使用 /doc 进行编译可以将文档注释处理到文件中。

示例

// xml_paramref_tag.cs

// compile with: /doc:xml_paramref_tag.xml

/// text for class MyClass

public class MyClass

{

/// <remarks>MyMethod is a method in the MyClass class.

/// The <paramref name="Int1"/> parameter takes a number.

/// </remarks>

public static void MyMethod(int Int1)

{

}

/// text for Main

public static void Main ()

{

}

9. <summary>

请参见

建议的文档注释标记

<summary>description</summary>

其中：

description

对象的摘要。

备注

<summary> 标记应当用于描述类型或类型成员。使用 <remarks> 添加针对某个类型说明的补充信息。

有关 <summary> 标记的文本是关于智能感知中类型信息的唯一来源，并且也显示在对象浏览器和代码注释 Web 报表中。

使用 /doc 进行编译可以将文档注释处理到文件中。

示例

// xml_summary_tag.cs

// compile with: /doc:xml_summary_tag.xml

/// text for class MyClass

public class MyClass

{

/// <summary>MyMethod is a method in the MyClass class.

/// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine"/> for information about output statements.</para>

/// <seealso cref="MyClass.Main"/>

/// </summary>

public static void MyMethod(int Int1)

{

}

/// text for Main

public static void Main ()

{

}

10. <exception cref="member">description</exception>

其中：

cref = "member"

对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后，将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。

description

说明。

备注

<exception> 标记使您可以指定哪些异常可被引发。该标记应用于方法定义。

使用 /doc 进行编译可以将文档注释处理到文件中。

示例

// xml_exception_tag.cs

// compile with: /doc:xml_exception_tag.xml

using System;

/// comment for class

public class EClass : Exception

{

// class definition ...

}

/// <exception cref="System.Exception">Thrown when... .</exception>

class TestClass

{

public static void Main()

{

try

{

}

catch(EClass)

{

}

11. <permission>

请参见

建议的文档注释标记

<permission cref="member">description</permission>

其中：

cref = "member"

对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。

description

对成员的访问的说明。

备注

<permission> 标记使您得以将成员的访问记入文档。System.Security.PermissionSet 使您得以指定对成员的访问。

使用 /doc 进行编译可以将文档注释处理到文件中。

示例

// xml_permission_tag.cs

// compile with: /doc:xml_permission_tag.xml

using System;

class TestClass

{

/// <permission cref="System.Security.PermissionSet">Everyone can access this method.</permission>

public static void Test()

{

}

public static void Main()

{

}

12. <value>

请参见

建议的文档注释标记

<value>property-description</value>

其中：

property-description

属性的说明。

备注

<value> 标记使您得以描述属性。请注意，当在 Visual Studio .NET 开发环境中通过代码向导添加属性时，它将会为新属性添加 <summary> 标记。然后，应该手动添加 <value> 标记以描述该属性所表示的值。

使用 /doc 进行编译可以将文档注释处理到文件中。

示例

// xml_value_tag.cs

// compile with: /doc:xml_value_tag.xml

using System;

/// text for class Employee

public class Employee

{

private string name;

/// <value>Name accesses the value of the name data member</value>

public string Name

{

get

{

return name;

}

set

{

name = value;

}

/// text for class MainClass

public class MainClass

{

/// text for Main

public static void Main()

{

}

13. <include>

请参见

建议的文档注释标记

其中：

filename

包含文档的文件名。该文件名可用路径加以限定。将 filename 括在单引号中 (' ')。

tagpath

filename 中指向标记名的标记路径。将此路径括在单引号中 (' ')。

name

注释前边的标记中的名称说明符；名称具有一个 id。

位于注释之前的标记的 ID。将此 ID 括在双引号中 (" ")。

备注

<include> 标记使您得以引用描述源代码中类型和成员的另一文件中的注释。这是除了将文档注释直接置于源代码文件中之外的另一种可选方法。

<include> 标记使用 XML XPath 语法。有关自定义 <include> 使用的方法，请参见 XPath 文档。

示例

以下是一个多文件示例。第一个文件使用 <include>，如下所列：

// xml_include_tag.cs

// compile with: /doc:xml_include_tag.xml

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />

class Test

{

public static void Main()

{

}

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />

class Test2

{

public void Test()

{

}

第二个文件 xml_include_tag.doc 包含下列文档注释：

The summary for this type.

</summary>

</MyMembers>

The summary for this other type.

</summary>

</MyMembers>

</MyDocs>

程序输出

<?xml version="1.0"?>

<doc>

</assembly>

The summary for this type.

</summary>

</member>

The summary for this other type.

</summary>

</member>

</members>

</doc>

14. <remarks>

请参见

建议的文档注释标记

<remarks>description</remarks>

其中：

description

成员的说明。

备注

<remarks> 标记用于添加有关某个类型的信息，从而补充由 <summary> 所指定的信息。此信息将显示在对象浏览器和代码注释 Web 报表中。

使用 /doc 进行编译可以将文档注释处理到文件中。

示例

// xml_remarks_tag.cs

// compile with: /doc:xml_remarks_tag.xml

/// <summary>

/// You may have some primary information about this class.

/// </summary>

/// <remarks>

/// You may have some additional information about this class.

/// </remarks>

public class MyClass

{

/// text for Main

public static void Main ()

{

}

15. <list>

请参见

建议的文档注释标记

<description>description</description>

</listheader>

<item>

<description>description</description>

</item>

</list>

其中：

term

要定义的项，该项将在 text 中定义。

description

项目符号列表或编号列表中的项或者 term 的定义。

备注

<listheader> 块用于定义表或定义列表中的标题行。定义表时，只需为标题中的项提供一个项。

列表中的每一项用 <item> 块指定。创建定义列表时，既需要指定 term 也需要指定 text。但是，对于表、项目符号列表或编号列表，只需为 text 提供一个项。

列表或表所拥有的 <item> 块数可以根据需要而定。

使用 /doc 进行编译可以将文档注释处理到文件中。

示例

// xml_list_tag.cs

// compile with: /doc:xml_list_tag.xml

/// text for class MyClass

public class MyClass

{

/// <remarks>Here is an example of a bulleted list:

/// <list type="bullet">

/// <item>

/// <description>Item 1.</description>

/// </item>

/// <item>

/// <description>Item 2.</description>

/// </item>

/// </list>

/// </remarks>

public static void Main ()

{

}

16. <returns>

请参见

建议的文档注释标记

<returns>description</returns>

其中：

description

返回值的说明。

备注

<returns> 标记应当用于方法声明的注释，以描述返回值。

使用 /doc 进行编译可以将文档注释处理到文件中。

示例

// xml_returns_tag.cs

// compile with: /doc:xml_returns_tag.xml

/// text for class MyClass

public class MyClass

{

/// <returns>Returns zero.</returns>

public static int GetZero()

{

return 0;

}

/// text for Main

public static void Main ()

{

}

转载自：http://hi.baidu.com/hopeforeverwyj/blog/item/a4c5024f989fe736aec3ab75.html