用途:该技能用于确保 C# 类型以 XML 注释编写文档,并遵循文档最佳实践。公共成员应使用 XML 注释编写文档;也鼓励为内部成员编写文档,尤其是复杂或含义不自明时。
主要能力:提供面向所有 API 的注释指引。使用 <summary> 提供类型或成员功能的一句话简述,以现在时第三人称动词开头;使用 <remarks> 补充实现细节、用法说明等上下文;使用 <see langword> 表示 null、true、false、int、bool 等语言关键字;使用 <c> 表示行内代码片段;使用 <example> 表示用法示例;使用 <code> 表示代码块,且应放在 <example> 内,并通过 language 属性标注语言,如 <code language="csharp">;使用 <see cref> 在句子中引用其他类型或成员;使用 <seealso> 在“另请参阅”部分独立引用;使用 <inheritdoc/> 继承基类或接口的文档,除非行为有重大变化,此时应记录差异。
方法与成员:使用 <param> 描述方法参数,描述应为不指定数据类型的名词短语并以冠词开头;标志枚举参数以“A bitwise combination of the enumeration values that specifies...”开头,非标志枚举以“One of the enumeration values that specifies...”开头;布尔参数采用“<see langword="true" /> to ...; otherwise, <see langword="false" />.”形式;out 参数采用“When this method returns, contains .... This parameter is treated as uninitialized.”形式。使用 <paramref> 引用参数名,<typeparam> 描述泛型类型参数,<typeparamref> 引用类型参数,<returns> 描述返回值,其描述同样为不指定数据类型的名词短语并以冠词开头;布尔返回值采用“<see langword="true" /> if ...; otherwise, <see langword="false" />.”形式。构造函数摘要应为“Initializes a new instance of the class [or struct].”。属性摘要:读写属性以“Gets or sets...”开头,只读属性以“Gets...”开头,返回布尔值的属性以“Gets [or sets] a value that indicates whether...”开头;使用 <value> 描述属性值,描述为不指定数据类型的名词短语;有默认值时另起一句说明,如“The default is <see langword="false" />”;布尔值类型采用“<see langword="true" /> if ...; otherwise, <see langword="false" />. The default is ...”形式。
异常:使用 <exception cref> 记录构造函数、属性、索引器、方法、运算符和事件抛出的异常;记录成员直接抛出的所有异常;对于嵌套成员抛出的异常,只记录用户最可能遇到的;异常描述说明抛出条件,省略“Thrown if ...”或“If ...”开头,直接陈述条件,例如“An error occurred when accessing a Message Queuing API.”。
限制:资料未提供该技能的具体安装方式、运行命令、平台支持、收费或价格信息。