C# 中文档标签的分隔符

介绍

代码文档描述了软件代码的意图。这包括类及其成员的意图或描述、参数和预期结果或返回值。C# 中有各种注释语法。其中之一是 XML 文档注释，有时称为 XML 注释。它们可以包含特定的 XML 标记（也称为文档标记），在创建文档文件后，文档查看器可以解释并以可视化方式显示这些标记。Visual Studio 和 VS Code 的 IntelliSense 功能可以利用它来显示有关类型或成员的信息。XML 文档注释必须紧接在用户定义类型（例如类、接口或委托）或其成员（例如字段、属性、方法或事件）之前。

XML 文档注释的使用需要分隔符，分隔符会告诉编译器文档注释的开始和结束位置。您可以使用单行分隔符或多行分隔符。

单行分隔符

单行分隔符以三重正斜杠///开头，后跟注释。如果分隔符后面有一个空格字符，则该字符不包含在 XML 输出中。它由 C# 项目模板使用，您会发现它在文档示例中也有使用。使用此分隔符，只有与斜杠在同一行的内容才被视为注释。

下面是使用单行分隔符的示例类：

      class Account
{
  /// <summary>Class constructor</summary>
  /// <param name="accountNo">the account number.</param>
  /// <param name="balance">the account balance.</param>
  public Account(string accountNo, int balance)
  {
    AccountNo = accountNo;
    Balance = balance;
  }

  /// <summary>Customer's account number </summary>
  public string AccountNo { get; set; }

  public int Balance { get; set; }
}
    

上面的代码对类构造函数和AccountNo属性进行了带单行分隔符的文档注释。构造函数的注释使用了三次分隔符。这是因为编译器只会将同一行中斜杠后面的内容读取为注释。Visual Studio IDE 有一项名为“智能注释编辑”的功能，在代码编辑器中键入 /// 分隔符后，它会自动插入斜杠、插入summary和/summary标记，并将光标移动到这些标记内。

多行分隔符

多行分隔符以/**开头，以*/结尾。它可以跨越多行，即此分隔符的起始字符在一行，结束字符在另一行，它们之间的任何文本作为注释。

下面是用于包含单行和多行注释的示例：

      class Account
{
  /** <summary>Class constructor</summary>
      <param name="accountNo">the account number.</param>
      <param name="balance">the account balance.</param>
  */
  public Account(string accountNo, int balance)
  {
    AccountNo = accountNo;
    Balance = balance;
  }

  /** <summary>Customer's account number </summary> */
  public string AccountNo { get; set; }

  public int Balance { get; set; }
}
    

从上面的示例中，只有以summary开头的部分才会被处理。三种标记格式会产生相同的注释。以下是使用此分隔符时需要注意的一些格式规则。

在包含/**分隔符的行上，如果该行的其余部分是空格，则不会处理该行的注释。

如果/**分隔符后的第一个字符是空格，则忽略该空格字符并处理该行的其余部分。否则，将/**分隔符后该行上的整个文本作为注释的一部分进行处理。

对于以/**分隔符开头的行之后的行，编译器会在每行的开头查找通用模式。如果编译器在每行的开头发现不以/**分隔符或*/分隔符开头的通用模式，它会忽略每行的该模式。该模式可以由星号后跟可选空格组成。

      /**
  * <summary>Class constructor</summary>
  * <param name="accountNo">the account number.</param>
  * <param name="balance">the account balance.</param>
*/
public Account(string accountNo, int balance)
{
  AccountNo = accountNo;
  Balance = balance;
}
    

在包含*/分隔符的行上，如果到*/分隔符为止只有空格，则忽略该行。否则，将文本作为注释的一部分进行处理，并遵守上面描述的模式匹配规则。

概括

文档注释对于帮助您或使用您代码的其他程序员更好地理解代码非常有用。它们可以包含某些推荐的标签，并且可以用两种方式分隔。使用单行分隔符或多行分隔符。您会在许多示例中看到单行分隔符，它是 C# 项目模板附带的默认分隔符。

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

_查看原文