C#：为 getter 和 setter 的具有不同访问器的属性编写摘要

Question

我在编写接口、classes、属性和方法的详细摘要方面非常自律。就在我专注于将我的代码分享给任何能够阅读的人时，无需花费任何不必要的解释。我遵循个人代码指南以确保一致性。

假设以下界面...

namespace CarFacility
{
  /// <summary>Represents the interface of all cars.</summary>
  public interface CarInterface
  {
    /// <summary>Gets the car serial number.</summary>
    string CarSerialNumber
    {
      get;
    }
  }
}

假设以下 class ...

namespace CarFacility
{
  /// <summary>Represents the base class of all cars.</summary>
  public abstract class CarAbstract:
    CarInterface
  {
    /// <summary>Stores the car serial number.</summary>
    private string _carSerialNumber = string.Empty;

    /// <summary>Gets / sets the car serial number.</summary>
    public virtual string CarSerialNumber
    {
      get
      {
        string carSerialNumber = this._carSerialNumber;
        return carSerialNumber;
      }
      private set
      {
        this._carSerialNumber = value;
      }
    }

    /// <summary>Creates a new car with a unique serial number.</summary>
    /// <param name="carSerialNumber">The unique car serial number of the car.</param>
    public CarAbstract( string carSerialNumber )
    {
      this.CarSerialNumber = carSerialNumber;
    }
  }
}

虽然汽车序列号通常不能更改，但其 setter 是私有的。
虽然可以在摘要中访问 setter，但它被记录为可设置。
针对接口实现仅显示 getter 的文档。
针对摘要的实施也显示了 setter，但是这个无法访问。

所以我的问题是如何编写适当的摘要以免混淆使用我的库的开发人员。我对您获得适当解决方案的最佳实践很感兴趣。

编辑

汽车序列号是从德语翻译成英语，表示底盘的唯一编号。它可能与最佳翻译不匹配。

这只是一个很接近的例子。想象一下，一辆新的 BMW 已在该工厂生产并获得了其唯一的序列号。您从 CarAbstract 派生出 class BMW，使用覆盖的构造函数创建它，但也传递唯一的汽车序列号。通过调用基本构造函数并传递此数字，您正在使用抽象的实现。

想象一个用例，您需要访问派生 BMW class 中的汽车序列号。所以代码帮助显示了 CarAbstract class 的属性的注释。有人可能会困惑地看到应该有一个 setter，但没有，因为它是私有的。

编辑

通过IList<CarInterface>，您可以遍历多辆汽车并读取汽车序列号。在类型转换为 CarInterface 时，代码帮助会向您显示界面的注释，其中仅包含 getter 的摘要。

Answer 1

我建议使用术语 "immutable"。

不可变通常描述属性仅在构造函数中设置且不可更改，因此它似乎符合您的要求。

C#：为 getter 和 setter 的具有不同访问器的属性编写摘要

C#: Writing summary for properties with different accessors for getter and setter

c#

properties

xml-comments