.net C# 注释使用详解

为方法增加示例代码：

    /// <summary>
    /// 初始化方法
    /// </summary>

///<example> 以下示例说明如何调用Add方法:
///<code>
///class MyClass
///{
///public static int Main()
///{
///return Add(1 + 2);
///}
///}
///</code>
///</example>
public override void Initialize()
{
IocManager.RegisterAssemblyByConvention(typeof(ApplicationModule).Assembly);
}

C#语言注释有三种形式

第一种是多行注释：

/*  */

例如：

/* int a=1;

   int b=2;

   int c=3;

  */

// 第二种是单行注释：

例如：

// int d=0;

第三种是文档注释

///  

例如：

/// <summary>This method changes the point's location by
/// the given x- and y-offsets.
/// <example>For example:
/// <code>
/// Point p = new Point(3,5);
/// p.Translate(-1,3);
/// </code>
/// results in <c>p</c>'s having the value (2,8).
/// </example>
/// </summary>

用于类的前面注释或者方法、属性前面注释

C#中的注释会换行

///会被编译，
//不会
所以使用///会减慢编译的速度（但不会影响执行速度）
///会在其它的人调用你的代码时提供智能感知

也是一种注释，但是这种注释主要有两种作用：
1.这些注释能够生成一个XML文件。这样呢,看起来会对程序的内容一目了然。
2.以这种方式对你的类，属性，方法等等加上注释之后，当你在其他地方使用以这种方式加上的类，属性，方法等等地时候，黄色的提示框里面会把你写的注释显示出来，是你更加明白你要使用的功能的作用。

///

///定义用户姓名属性，该属性为可读可写属性

///

C# Coding的时候，常常涉及代码注释，常见的注释包括两类：

1）单行注释。格式：// Comments

2）多行注释。格式：/* Comments... */

C#引入了新的XML注释，即我们在某个函数前新起一行，输入///，VS.Net会自动增加XML格式的注释，这里整理一下可用的XML注释。

XML注释分为一级注释（Primary Tags）和二级注释（Secondary Tags），前者可以单独存在，后者必须包含在一级注释内部。

I 一级注释

1. 对类型进行描述，功能类似

，据说建议使用;

2.

对共有类型的类、方法、属性或字段进行注释；3. 主要用于属性的注释，表示属性的制的含义，可以配合使用；

4.

用于对方法的参数进行说明，格式：value；5. 用于定义方法的返回值，对于一个方法，输入///后，会自动添加、列表和；

6. 定义可能抛出的异常，格式：；

7. 用于给出如何使用某个方法、属性或者字段的使用方法；

8. 涉及方法的访问许可；

9. 用于参考某个其它的东东:)，也可以通过cref设置属性；

10. 用于指示外部的XML注释；

II 二级注释

1. or 主要用于加入代码段；

2. 的作用类似HTML中的

标记符，就是分段；

3. 用于引用某个参数；

4. 的作用类似，可以指示其它的方法；

5. 用于生成一个列表；

另外，还可以自定义XML标签 

 

二、让C#智能注释时显示为换行

在C#智能注释时，常常希望它能在开发时显示为换行，使得提示更加友好！原来一直想怎么实现，今天偶然发现原来如此简单，只需将 标记用于诸如

、 或 等标记内即可。     注释在开发时换行显示的办法  标记用于诸如 、 或 等标记内，使您得以将结构添加到文本中。 ///  /// 基类（第1行） ///说明：（第2行） ///　　封装一些常用的成员（第3行） ///　　前面要用全角空格才能显示出空格来（第4行） ///  public class MyBase {       ///        /// 构造函数（第1行）       ///说明：（第2行）       ///　　初始化一些数据（第3行）       ///        public MyBase()       {             //             //TODO: 在此处添加构造函数逻辑             //        } } 

（C# 编程指南）

发布于 2019-11-12 07:35:32 字数 1027 浏览 1173 评论 0 收藏 0

<example>description</example>

参数

description

代码示例的说明。

备注

使用

标记可以指定使用方法或其他库成员的示例。这通常涉及使用 标记。

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

示例

C#

复制代码

// compile with: /doc:DocFileName.xml /// text for class TestClass public class TestClass { /// <summary> /// The GetZero method. /// </summary> /// <example> This sample shows how to call the GetZero method. /// <code> /// class TestClass /// { /// static int Main() /// { /// return GetZero(); /// } /// } /// </code> /// </example> public static int GetZero() { return 0; } /// text for Main static void Main() { } }

请参见

概念C# 编程指南

参考

using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Threading.Tasks; namespace XDC { /// Comment for class public class EClass : System.Exception { // class definition... } class XML_Documentation_Comments { /// <summary> /// <c>Tag_c</c> is a method in the <c>XML_Documentation_Comments</c> class. /// </summary> public static void Tag_c(int Int1) { //语法 XML <c>text</c> //参数 text 要指示为代码的文本。 //备注 使用 <c> 标记可以指示应将说明内的文本标记为代码。 使用 <code> 指示作为代码的多行文本。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 } /// <summary> /// The Tag_code method. /// </summary> /// <example> /// This sample shows how to call the <see cref=Tag_code/> method. /// <code> /// class XML_Documentation_Comments /// { /// static int Main() /// { /// return Tag_code(); /// } /// } /// </code> /// </example> public static int Tag_code() { //语法 XML <code>content</code> //参数 content 要标记为代码的文本。 //备注 <code> 标记可将多行内容指示为代码。 使用 <c> 指示应将说明内的文本标记为代码。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 return 0; } /// <summary> /// The Tag_example method. /// </summary> /// <example> /// This sample shows how to call the <see cref=Tag_example/> method. /// <code> /// class XML_Documentation_Comments /// { /// static int Main() /// { /// return Tag_example(); /// } /// } /// </code> /// </example> public static int Tag_example() { //语法 XML <example>description</example> //参数 description 代码示例的说明。 //备注 借助 <example> 标记，可以指定如何使用方法或其他库成员的示例。 这通常涉及到使用 <code> 标记。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 return 0; } /// <exception cref=System.Exception>Thrown when...</exception> public void Tag_exception() { try { //语法 XML <exception cref=member>description</exception> //参数 cref=member 对当前编译环境中出现的一个异常的引用。 编译器检查是否存在给定的异常，并将 member 转换为输出 XML 中的规范的元素名称。 // member 必须出现在双引号 ( ) 内。 // 有关如何设置 member 格式以引用泛型类型的详细信息，请参阅处理 XML 文件。 // description 异常的说明。 //备注 <exception> 标记让你指定可引发的异常。 此标记可应用于方法、属性、事件和索引器的定义。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 // 有关异常处理的详细信息，请参阅异常和异常处理。 } catch (EClass) { } } /// <summary> /// Here is an example of a bulleted list: /// <list type=bullet> /// <item> /// <description>Item 1.</description> /// </item> /// <item> /// <description>Item 2.</description> /// </item> /// </list> /// </summary> public void Tag_list() { //语法 XML // <list type=bullet | number | table> // < listheader > // < term > term </ term > // < description > description </ description > // </ listheader > // < item > // < term > term </ term > // < description > description </ description > // </ item > // </ list > //参数 // term 要定义的术语，将在 description 中进行定义。 // description 项目符号或编号列表中的项或 term 的定义。 //备注 // <listheader> 块用于定义表或定义列表的标题行。 定义表时，只需提供标题中的术语的项。 // 列表中的每个项均使用 <item> 块指定。 创建定义列表时，需要同时指定 term 和 description。 但是，对于表、项目符号列表或编 // 号列表，只需提供 description 的项。 // 列表或表可根据需要具有多个 <item> 块。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 } /// <summary> /// <para>para 1</para> /// <para>para 2</para> /// </summary> public void Tag_para() { //语法 XML // <para>content</para> //参数 // content 段落文本。 //备注 // <para> 标记用于标记内，例如 <summary>、<remarks> 或 <returns>，允许向文本添加结构。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 } /// <summary> /// Multiple parameters. /// </summary> /// <param name=Int1>Used to indicate status.</param> /// <param name=Float1>Used to specify context.</param> public void Tag_param(int Int1, float Float1) { //语法 XML // <param name=name>description</param> //参数 // name 方法参数的名称。 用双引号 ( ) 将名称引起来。 // description 参数的说明。 //备注 // 在方法声明的注释中，应使用 <param> 标记来描述方法参数之一。 若要记录多个参数，请使用多个 <param > 标记。 // <param> 标记的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报表中。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 } /// <summary> /// Tag_paramref is a method in the XML_Documentation_Comments class. /// The <paramref name=Int1/> parameter takes a number. /// </summary> /// <param name=Int1></param> public void Tag_paramref(int Int1) { //语法 XML // <paramref name=name/> //参数 // name 要引用的参数的名称。 用双引号 ( ) 将名称引起来。 //备注 // <paramref> 标记提供一种方式，用于指示 <summary> 或 <remarks> 块等代码注释中的单词引用某个参数。 可以处理 XML 文件以明 // 显的方式设置此单词的格式，如使用粗体或斜体。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 } /// <permission cref=System.Security.PermissionSet>Everyone can access this method.</permission> public void Tag_permission() { //语法 XML // <permission cref=member>description</permission> //参数 // cref=member 对可从当前编译环境调用的成员或字段的引用。 编译器检查是否存在给定的代码元素，并将 member 转换为输出 // XML 中规范的元素名称。 成员必须出现在双引号 ( ) 内。 // 有关如何创建对泛型类型的 cref 引用的信息，请参阅 <see>。 // description 对成员访问权限的说明。 //备注 // 使用 <permission> 可以记录成员访问权限 PermissionSet 类可指定对成员的访问权限。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 } /// <returns>Returns zero.</returns> public int Tag_returns() { //语法 XML // <returns>description</returns> //参数 // description 返回值的说明。 //备注 // 在方法声明的注释中应使用 <returns> 标记来描述返回值。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 return 0; } /// <summary>Tag_see is a method in the XML_Documentation_Comments class. /// <para>Here's how you could make a second paragraph in a description. <see cref=System.Console.WriteLine(System.String)/> for information about output statements.</para> /// <seealso cref=XML_Documentation_Comments.Tag_see/> /// </summary> public int Tag_see() { //语法 XML // <see cref=member/> //参数 // cref=member 对可从当前编译环境调用的成员或字段的引用。 编译器检查是否存在给定的码位元素，并将 member 传递到输出 XML 中的元素名称。 // 将成员置于双引号 ( ) 内。 //备注 // 通过 <see> 标记可以从文本内指定链接。 使用 <seealso> 指示文本应该放在“另请参阅”部分中。 使用 cref 属性创建指向代码元素的文 // 档页的内部超链接。 // 使用 /doc 进行编译以便将文档注释处理到文件中。 return 0; } /// <summary>Tag_seealso is a method in the XML_Documentation_Comments class. /// <para>Here's how you could make a second paragraph in a description. <see cref=System.Console.WriteLine(System.String)/> for information about output statements.</para> /// <seealso cref=XML_Documentation_Comments.Tag_see/> /// </summary> public int Tag_seealso() { //语法 XML // <seealso cref=member/> //参数 // cref=member 对可从当前编译环境调用的成员或字段的引用。 编译器检查是否存在给定的码位元素，并将 member 传递到输出 XML 中的元素名称。 // member 必须在双引号 ( ) 内。 // 有关如何创建对泛型类型的 cref 引用的信息，请参阅 <see>。 //备注 // 使用 <seealso> 标记，可以指定想要在“另请参阅”部分中显示的文本。 使用 <see> 从文本内指定链接。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 return 0; } /// <summary>Tag_summary is a method in the XML_Documentation_Comments class. /// <para>Here's how you could make a second paragraph in a description. <see cref=System.Console.WriteLine(System.String)/> for information about output statements.</para> /// <seealso cref=XML_Documentation_Comments.Tag_see/> /// </summary> public int Tag_summary() { //语法 XML // <summary>description</summary> //参数 // description 对象的摘要。 //备注 // <summary> 标记应当用于描述类型或类型成员。 使用 <remarks> 可针对某个类型说明添加补充信息。 使用 cref 属性可启用文档工 // 具（如 DocFX 和 Sandcastle）来创建指向代码元素的文档页的内部超链接。 // <summary> 标记的文本是唯一有关 IntelliSense 中的类型的信息源，它也显示在对象浏览器窗口中。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 若要基于编译器生成的文件创建最终文档，可以创建一个自定义工具，也可以使用 // DocFX 或 Sandcastle 等工具。 return 0; } /// <summary> /// Creates a new array of arbitrary type <typeparamref name=T/> /// </summary> /// <typeparam name=T>The element type of the array</typeparam> public static T[] Tag_typeparam<T>(int n) { //语法 XML // <typeparam name=name>description</typeparam> //参数 // name 类型参数的名称。 用双引号 ( ) 将名称引起来。 // description 类型参数的说明。 //备注 // 在泛型类型或方法声明的注释中，应使用 <typeparam> 标记来描述类型参数。 为泛型类型或方法的每个类型参数添加标记。 // 有关详细信息，请参阅泛型。 // <typeparam> 标记的文本将显示在 IntelliSense、对象浏览器窗口代码注释 Web 报表。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 return new T[n]; } /// <summary> /// Creates a new array of arbitrary type <typeparamref name=T/> /// </summary> /// <typeparam name=T>The element type of the array</typeparam> public static T[] Tag_typeparamref<T>(int n) { //语法 XML // <typeparamref name=name/> //参数 // name 类型参数的名称。 用双引号 ( ) 将名称引起来。 //备注 // 有关泛型类型中的类型参数及方法的详细信息，请参阅泛型。 // 通过此标记，文档文件的使用者可显著设置字体格式，例如采用斜体。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 return new T[n]; } private string _name; /// <summary>The Name property represents the employee's name.</summary> /// <value>The Name property gets/sets the value of the string field, _name.</value> public string Tag_value { //语法 XML // <value>property-description</value> //参数 // property-description 属性的说明。 //备注 // <value> 标记可以描述属性表示的值。 请注意，在 Visual Studio .NET 开发环境中通过代码向导添加属性时，将添加新属性的 // <summary> 标记。 然后，应手动添加 <value> 标记，描述属性表示的值。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 get { return _name; } set { _name = value; } } public class Tag_cref_Attribute { //XML 文档标记中的 cref 属性是指“代码引用”。 它指定标记的内部文本是一个代码元素，例如类型、方法或属性。 文档工具（例如 DocFX 和 Sandcastle）使用 cref 属性自动生成指向记录类型或成员的页面的超链接。 /// <summary> /// This sample shows how to specify the <see cref=Tag_cref_Attribute/> constructor as a cref attribute. /// </summary> public Tag_cref_Attribute() { } /// <summary> /// This sample shows how to specify the <see cref=Tag_cref_Attribute(int)/> constructor as a cref attribute. /// </summary> public Tag_cref_Attribute(int value) { } /// <summary> /// The GetZero method. /// </summary> /// <example> /// This sample shows how to call the <see cref=GetZero/> method. /// <code> /// class TestClass /// { /// static int Main() /// { /// return GetZero(); /// } /// } /// </code> /// </example> public static int GetZero() { return 0; } /// <summary> /// The GetGenericValue method. /// </summary> /// <remarks> /// This sample shows how to specify the <see cref=GetGenericValue/> method as a cref attribute. /// </remarks> public static T GetGenericValue<T>(T para) { return para; } /// <summary> /// GenericClass. /// </summary> /// <remarks> /// This example shows how to specify the <see cref=GenericClass{T}/> type as a cref attribute. /// </remarks> class GenericClass<T> { // Fields and members. } class Program { static int Main() { return Tag_cref_Attribute.GetZero(); } } } /// <summary> /// You may have some primary information about this class. /// </summary> /// <remarks> /// You may have some additional information about this class. /// </remarks> public class Tag_remark { //语法 XML // <remarks>description</remarks> //参数 // description 对成员的说明。 //备注 // <remarks> 标记用于添加有关某个类型的信息，从而补充由 <summary> 指定的信息。 此信息显示在对象浏览器窗口中。 // 使用 /doc 进行编译可以将文档注释处理到文件中。 static void Main() { } } /// <include file='xml_include_tag.xml' path='MyDocs/MyMembers[@name=test]/*' /> public class Tag_include { /// <include file='xml_include_tag.xml' path='MyDocs/MyMembers[@name=test2]/*' /> static void Main() { //语法 // XML <include file='filename' path='tagpath[@name=id]' /> //参数 // filename 包含文档的 XML 文件的名称。 可使用相对于源代码文件的路径限定文件名。 使用单引号 (' ') 将 filename 括起来。 // tagpath filename 中标记的路径，它指向标记 name。 使用单引号 (' ') 将路径括起来。 // name 标记中的名称说明符（位于注释之前）；name 将有 id。 // id 标记的 ID（位于注释之前）。 用双引号 ( ) 将 ID 括起来。 //备注 // 通过 <include> 标记，可在其他文件中引用描述源代码中类型和成员的注释。 这是对直接在源代码文件中放入文档注释的替代方法。 // 通过将文档放入不同文件，可以单独从源代码对文档应用源控件。 一人可以签出源代码文件，而其他人可以签出文档文件。 // <include> 标记使用 XML XPath 语法。 有关如何自定义 <include> 的用法，请参阅 XPath 文档。 //xml_include_tag.xml 包含在项目中 //文件属性 // 复制到输出目录 不复制 // 生成操作 内容 // // <?xml version=1.0 encoding=utf-8?> // < 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 > } } } }