.net - 如何正确记录扩展方法

Question

所以，我有一些扩展方法，用于常用的东西，在记录它们时，我突然想到我不知道如何一致地编写 summary XML 注释中的标记。例如:

    /// <summary>
    ///     Gets a subset of characters from the left-hand side of a string.
    /// </summary>
    public static string Left(this string value, int length)

对比

    /// <summary>
    ///     Gets the name of the month for this date.
    /// </summary>
    public static string MonthName(this DateTime value)

所以，问题似乎是我不知道如何始终如一地提到那个讨厌的 this范围。此外，我不知道如何清楚地表明这是一种扩展方法(因为我不确定 SandcaSTLe 和其他工具是否已经 catch 它们并且可以自动注释文档以显示它)；我不想稍后撕掉所有的手动文档。

所以问题是，记录扩展方法有哪些指南？如果没有正式的指导，大家都是怎么处理的？如果我们还没有，我们可以对某些事情进行投票，以便我有事情要做吗？作为一个强制症控制狂，这种不一致让我发疯。

Answer 1

不支持扩展方法的 .NET 语言将要求用户直接调用该方法并传入本来可以扩展的对象。因此，重要的是记录此参数并准确描述为什么需要它以及该方法将如何对它起作用。

从扩展方法方面考虑这可能有点困难，但是如果您从人们调用静态方法的另一方设想方法，那就更容易了。

另一件事... 有时您可能会发现自己(如 MVC 中的 HtmlHelper)在那里扩展对象超出约定而不是必要性。这意味着被扩展的对象是否为空并不重要，因为该方法不会对其进行操作。而约定(我相信)是在 this 时抛出对象为空，我更喜欢让方法正常完成并在帮助中记录这一事实(即“...这可以为空”或“...空是此参数的有效值。”)