C# 中的 XML 文档注释

介绍

代码文档描述了软件代码的意图。这包括类及其成员的意图或描述、参数和预期结果或返回值。C# 中有各种注释语法。其中之一是 XML 文档注释，有时也称为 XML 注释，以三斜杠 - ///开头。Visual Studio 和 VS Code 的 IntelliSense 功能可以利用 XML 注释显示有关类型或成员的信息；此信息来自您在代码文档中输入的内容。.NET 编译器有一个选项可以读取 XML 文档注释并从中生成 XML 文档。可以将此 XML 文档提取到单独的 XML 文件中。XML 文档注释必须紧接着用户定义类型（如类、接口或委托）或其成员（如字段、属性、方法或事件）。

XML 文档注释

让我们看一个简单的类，如下所示：

      class Program
{
 static void Main(string[] args)
 {
   Console.WriteLine("Hello World!");

   Console.ReadKey();
 }

 ///The left side operand for an arithmetic operation
 static int Operand1 { get; set; }

 ///The right side operand for an arithmetic operation
 static int Operand2 { get; set; }

 /// This method adds two integers
 static int Add(int operand1, int operand2)
 {
   return operand1 + operand2;
 }

 ///This method subtracts two integers
 static int Subtract(int operand1, int operand2)
 {
   return operand1 - operand2;
 }
}
    

我们为属性Operand1和Operand2以及方法Add和Subtract添加了 XML 注释。当您使用 XML 注释调用这些属性或方法中的任何一个时，它们都会显示文本描述。

有一些推荐的 XML 标签可以与 XML 注释一起使用。它们是<remarks>、<summary>和<returns>标签。

备注标签

<remarks>标签指定类型（例如类或结构）的一般注释或描述。

      ///<remarks>Holds user basic data like their names and address
class User
{
 string FirstName { get; set; }

 string LastName { get; set; }
}
    

摘要标签

<summary>标签用于添加一般注释，解释某个方法或其他类成员。如果<remarks>是针对某个类的一般注释，那么<summary> 的作用也是一样的，只不过针对的是该类的成员。

      ///<summary>Subtract two integers and return the result</summary>
static int Subtract(int operand1, int operand2)
{
 return operand1 + operand2;
}
    

退货标签

<returns>标签记录方法的返回值。因此，我们可以更新上面的代码以添加<returns>标签，如下所示：

      ///<summary>Subtract two integers and returns the result</summary>
///<returns>the difference between the two operands</returns>
static int Subtract(int operand1, int operand2)
{
 return operand1 + operand2;
}
    

最终结果

应用标签将如下所示：

      ///<remarks>Starts the console application</remarks>
class Program
{
 static void Main(string[] args)
 {
   Console.WriteLine("Hello World!");

   Console.ReadKey();
 }

 ///The left side operand for an arithmetic operation
 static int Operand1 { get; set; }

 ///The right side operand for an arithmetic operation
 static int Operand2 { get; set; }

 ///<summary>Adds two integers and return the result</summary>
 ///<returns>the difference between the two operands</returns>
 static int Add(int operand1, int operand2)
 {
   return operand1 + operand2;
 }

 ///<summary>Subtract two integers and return the result</summary>
 ///<returns>the difference between the two operands</returns>
 static int Subtract(int operand1, int operand2)
 {
   return operand1 - operand2;
 }
}
    

然后，当我们想要使用任何类成员时，就可以获得 IntelliSense

包起来

XML 文档注释对于帮助您或将使用您的代码的其他程序员更好地理解代码非常有用。我们研究了三个推荐的标签，以及一个包含使用它们的成员的类。您从这些注释中看到了它如何提供 IntelliSense 信息。

尽可能多地使用 XML 文档，让代码更有意义。请参阅 C#文档以获取更多推荐的标签。

_{免责声明：本内容来源于第三方作者授权、网友推荐或互联网整理，旨在为广大用户提供学习与参考之用。所有文本和图片版权归原创网站或作者本人所有，其观点并不代表本站立场。如有任何版权侵犯或转载不当之情况，请与我们取得联系，我们将尽快进行相关处理与修改。感谢您的理解与支持！}

_查看原文