VS XML注释
1.<c>
<c>text</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>
请参见
建议的文档注释标记
<see cref="member"/>
其中：
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>
请参见
建议的文档注释标记
<seealso cref="member"/>
其中：
cref = "member"
对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后，将 member 传递给输出 XML
中的元素名。必须将 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>
请参见
建议的文档注释标记
<paramref name="name"/>
其中：
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>
请参见
建议的文档注释标记
<include file='filename' path='tagpath[@name="id"]'
/>
其中：
filename
包含文档的文件名。该文件名可用路径加以限定。将 filename 括在单引号中 (' ')。
tagpath
filename 中指向标记名的标记路径。将此路径括在单引号中 (' ')。
name
注释前边的标记中的名称说明符；名称具有一个 id。
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 包含下列文档注释：
<MyDocs>
<MyMembers name="test">
<summary>
The summary for this type.
</summary>
</MyMembers>
<MyMembers name="test2">
<summary>
The summary for this other type.
</summary>
</MyMembers>
</MyDocs>
程序输出
<?xml version="1.0"?>
<doc>
<assembly>
<name>t2</name>
</assembly>
<members>
<member name="T:Test">
<summary>
The summary for this type.
</summary>
</member>
<member name="T:Test2">
<summary>
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>
请参见
建议的文档注释标记
<list type="bullet" | "number" |
"table">
<listheader>
<term>term</term>
<description>description</description>
</listheader>
<item>
<term>term</term>
<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
