用好各种注释

<overloads>

新增标记,允许您为重载的成员提供文档。您只需要为重载的第一个成员定义即可。

<overloads> 标记有以下两种形式:

· 简单方式:只包含文本说明,将被视作重载成员总体的 summary。

· 详细方式:您可以提供更详细的包含 summary, remarks, example 等标记的文档。

示例:

 
///<overloads>此方法有两次重载。问好。</overloads>
///<summary>此方法仅问好。</summary>
public void SayHello() { ... }
///<summary>此方法向某人问好。</summary>
public void SayHello(string toSomeone) { ... }

<param>

定义方法成员的参数。参见 Microsoft 的定义。

<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 ()

   {

   }

}

<permission>

定义成员的访问。参见 Microsoft 的定义。

<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()

   {

   }

}

<remarks>

“备注”节。参见 Microsoft 的定义。

<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 ()

   {

   }

}

<returns>

定义成员的返回值。参见 Microsoft 的定义。

<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 ()

   {

   }

}

<seealso>

“请参见”节添加链接。参见 Microsoft 的定义。

不要 将此标记放在  <remarks> 节中。

扩展的语法:

· <seealso href="/url">[label]</seealso>

· <seealso cref="member">[label]</seealso>

<seealso>请参见

建议的文档注释标记

<seealso cref="member"/>

其中:

cref = "member"

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

备注

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

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

示例

有关使用 <seealso> 的示例,请参见 <summary>。

<summary>

定义对象的摘要。参见 Microsoft 的定义。

<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 ()

   {

   }

}

<value>

定义属性值。参见 Microsoft 的定义。

<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()

   {

   }

}

posted @ 2007-04-30 11:47  chinaifne  阅读(440)  评论(0编辑  收藏  举报