SuperAPI AI 工具集

csharp-docs

编程与开发

查看项目

更新于 10-15 21:52

技能介绍

用途:确保 C# 类型使用 XML 注释进行文档化,并遵循文档编写最佳实践。

主要能力与规范要点: 公共成员应使用 XML 注释;内部成员若复杂或不易自解释,也建议记录。 通用 API 指引:用 <summary> 写一句话简述类型或成员的作用,以现在时第三人称动词开头;用 <remarks> 补充实现细节、使用说明等;语言关键字(如 null、true、false、int、bool)用 <see langword>;行内代码用 <c>;用法示例用 <example>;代码块用 <code>,且 <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.”。

使用方式与限制:资料未提供具体安装命令、工具集成方式或运行步骤,暂未提供。