C#文档中如何引用其他属性以支持重构同步?
问题描述
现有如下C#类:
public sealed class Person { public string FirstName { get; set; } public string LastName { get; set; } public string DisplayName => $"{FirstName} {LastName}"; }
需要为DisplayName属性编写文档注释,当前写法如下:
/// <summary> /// 由FirstName和LastName组成的空格分隔字符串 /// </summary> public string DisplayName => $"{FirstName} {LastName}";
问题在于:如果把LastName重命名为FamilyName,代码可正常编译,但文档注释仍会引用已不存在的LastName属性。想知道是否存在类似如下伪语法的写法:
/// <summary> /// 由<prop=FirstName>和<prop=LastName>组成的空格分隔字符串 /// </summary>
能让重构代码时文档同步更新,或让编译器针对这种文档与代码不一致的情况给出警告/错误?
解决方案
使用标准XML文档注释的
<see>标签
C#原生支持用<see cref="成员名称"/>标签在文档注释中引用代码元素。使用该标签替代直接书写属性名后,主流IDE(如Visual Studio、JetBrains Rider)的重命名重构功能会自动同步更新文档里的引用;部分静态分析工具还能检测无效的cref引用并给出警告。
示例写法:/// <summary> /// 由<see cref="FirstName"/>和<see cref="LastName"/>组成的空格分隔字符串 /// </summary> public string DisplayName => $"{FirstName} {LastName}";启用静态分析规则
开启相关代码分析规则(如CA1200:避免使用cref标签的重载形式,或专门检测无效XML注释引用的规则),当文档中的cref指向不存在的成员时,编译器会抛出警告或错误,强制你同步更新文档内容。依赖IDE的重构支持
只要使用标准的<see cref="..."/>标签,Visual Studio、JetBrains Rider等主流IDE在对类成员执行重命名操作时,会自动扫描所有XML文档注释中的引用并同步更新,确保文档与代码的一致性。
内容的提问来源于stack exchange,提问作者Wouter Vandenputte
相关产品推荐
相关产品推荐

