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

时间: 2024-09-20 06:18:23

VS XML注释的相关文章

在C#使用XML注释

xml     简介     大多数程序员可能都听说过Java自带的一个工具JavaDoc:使用它可以自动地为你的代码生成HTML文档.C#和C#编译器也有类似的功能,不过它生成的是XML,而不是直接生成HTML.不过使用XML会使得文档更加灵活.     注释语法     为了使用C#提供的XML注释功能,你的注释应该使用特殊的注释语法(///)开头.在///之后,你可以使用预先定义的标签注释你的代码,也可以插入你自己定义的标签.你定制的标签将会在随后加入到生成的注释文档中.     预定义的

在C#使用XML注释 选择自 lotusswan 的 Blog

xml 在C#使用XML注释 简介 大多数程序员可能都听说过Java自带的一个工具JavaDoc:使用它可以自动地为你的代码生成HTML文档.C#和C#编译器也有类似的功能,不过它生成的是XML,而不是直接生成HTML.不过使用XML会使得文档更加灵活. 注释语法 为了使用C#提供的XML注释功能,你的注释应该使用特殊的注释语法(///)开头.在///之后,你可以使用预先定义的标签注释你的代码,也可以插入你自己定义的标签.你定制的标签将会在随后加入到生成的注释文档中. 预定义的标签 用处 <c>

Visual Studio.net中的XML注释

visual|xml Visual Studio.net中的XML注释10/18/2001 11:1:33· · ··YESKY 在XML文件中应用XSL模板 你现在将要把XSL模板应用于你创建的XML文件.你要在IDE中打开XML和XSL文件,然后再应用XSL模板,这样XML.doc才可以正确地在Web浏览器中显示. 1.在IDE中,点击File,再点击Add Existing Item. 2.打开路径C:\Documents and Settings\Administrator\My Doc

Visual Studio.net中的XML注释 (1)

visual|xml Visual Studio.net中的XML注释10/18/2001 11:1:33· · ··YESKY 介绍 在这个实践练习中,你将在C#源文件中插入XML注释,然后通过C#编译器生成XML文件.你可以在C#源代码中使用XML相关的注释标记,这些标记被用来指明哪些注释需要输出到XML文件. XML文件可以作为代码文档.你可以在现存的文件中加入新的注释,或者修改现有注释,以保持文档和它对应代码的一致性.为了创建一个更新的文档记录,你要重新生成XML文件. 在本练习中,你将

在C#中使用XML注释

大多数程序员可能都听说过Java自带的一个工具JavaDoc:使用它可以自动地为你的代码生成HTML文档.C#和C#编译器也有类似的功能,不过它生成的是XML,而不是直接生成HTML.不过使用XML会使得文档更加灵活. 注释语法 为了使用C#提供的XML注释功能,你的注释应该使用特殊的注释语法(///)开头.在///之后,你可以使用预先定义的标签注释你的代码,也可以插入你自己定义的标签.你定制的标签将会在随后加入到生成的注释文档中. 预定义的标签 用处 <c> 将说明中的文本标记为代码 <

Visual Basic 2005在语言上的增强(三)XML注释

XML注释允许你在代码中添加结构化的文档,并且因为这是C#最先采用的技术,Visual Basic程序员觊觎已久了.XML注释能够描述各种各样的代码元素,包括类.字段成员.方法.以及枚举等等.一旦你创建了一个描述代码特性的XML注释,当你继续在编辑器里键入代码特性时,你立刻会得到关于参数和返回值的智能感知.假设你现在有一个标志着如下签名的函数原型:Private Function GetCustomerData(ByVal CustomerCode As String) As DataSet把代

Visual C++ 2005中的XML注释

C#程序员可以用三个斜杠来开始XML格式的注释,而且编译器可以据此生成可用于自动生成帮助文档的XML文件.Visual C++ 2005中的编译器也支持了这个功能,而且对非托管函数也生效,前提是必须打开/clr和/DOC开关,并且不能使用/clr:oldSyntax开关编译. /**///////Use two bubble sort steps ///to show the performance information///of different function calls./// in

xml注释-XmlSerializer序列化时是不是不能加注释

问题描述 XmlSerializer序列化时是不是不能加注释 public class Rule { public string device; public int channel; } //序列化List private void Serialize(List list) { XmlDocument xd = new XmlDocument(); using (StringWriter sw = new StringWriter()) { try { XmlSerializer xz = n

XML注释快捷键

注释:CTRL + SHIFT + / 撤销注释:CTRL + SHIFT + \ 真是被以前的自己给蠢哭了,一行行地敲.....