如何正确记录扩展方法

Question

所以，我有一些扩展方法，对于常用的东西，并且在记录它们时，我发现我不知道如何一致地编写摘要 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)

VS

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

所以，问题似乎是我不知道如何一致地引用那个讨厌的 this 参数。此外，我不知道如何清楚地表明这是一种扩展方法（因为我不确定Sandcastle和其他工具是否已经赶上它们并且可以自动注释文档以显示它）;我不想在以后撕掉所有的手册文档。

所以问题是，有什么指导来记录扩展方法？如果没有正式的指导，你们怎么处理呢？如果我们没有，我们可以对某些事情进行投票，这样我就可以继续吗？作为一个强迫性的控制狂，这种不一致让我很生气。

Answer 1

不支持扩展方法的.NET语言将要求用户直接调用该方法并传入已扩展的对象。因此，记录此参数并准确描述其所需的原因以及该方法如何对其起作用非常重要。

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

另一件事......有时候你可能会发现自己（比如MVC中的HtmlHelper）你正在从约定中扩展一个对象而不是必需。这意味着被扩展的对象是否为null并不重要，因为该方法不会对其起作用。虽然约定（我相信）是在 this 对象为null时抛出，但我更喜欢让方法正常完成并在帮助中记录这个事实（即“...这可以是null“或”“... null是此参数的有效值。”）