How to properly document an extension method

Question

So, I have a few extension methods, for commonly used stuff, and in documenting them, it's occurred to me that I have no idea how to consistently write the summary tag in the XML comments. For example:

    /// <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)

So, the problem seems to be that I don't know how to consistently refer to that pesky this parameter. Further, I don't know how to clearly indicate that this is an extension method (since I'm not certain that Sandcastle and other tools have caught up to them yet and can automatically annotate the documentation to show it); I'd hate to have to rip all that manual documentation out later.

So the question is, what guidance is there for documenting extension methods? If there is no formal guidance, how do you all handle it? If we haven't, can we vote on something so I have something to go on? As an obsessive compulsive control freak, this inconsistency is driving me mad.

Answer 1

.NET languages that don't support extension methods will require users call the method directly and pass in the object that would have been extended. Therefore it is important to document this parameter and describe exactly why it is needed and how the method will act upon it.

This can be a little hard to think about from the extension method side, but if you envision the method from the other side, where people are calling a static method, its easier.

One other thing... Sometimes you might find yourself (like the HtmlHelper in MVC) where you are extending an object out of convention rather than necessity. This means it doesn't matter if the object that is being extended is null or not because the method does not act upon it. While the convention (I believe) is to throw when the this object is null, I prefer to let the method complete normally and document this fact in the help (i.e., "... This can be null" or "... null is a valid value for this argument.")

Answer 2

I've been fighting over this question myself and I've yet to come to a conclusion. For a while I took to naming the this object "this". It seems like a natural thing to do in VB, but then I'm not treating it like a normal function which it also it.