How to properly document an extension method

Question

So, I have several extension methods for commonly used material, and when documenting them, it occurred to me that I had no idea how to write the summary tag sequentially in XML comments. For instance:

  /// <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 is that I do not know how to refer to this pesky this parameter sequentially. In addition, I do not know how to clearly indicate that this is an extension method (since I am not sure that Sandcastle and other tools have caught up with them, and can automatically annotate the documentation to show it); I would not want to break all this manual documentation later.

So the question is, what is a guide for documenting extension methods? If there are no official guidelines, how do you deal with this? If we do not, can we vote for something so that I have something else? Like an obsessive compulsive control freak, this inconsistency drives me crazy.

Answer 1

.NET languages ​​that do not support extension methods require users to call the method directly and pass in an object that would be extended. Therefore, it is important to document this parameter and accurately describe why it is needed, and how the method will act on it.

You can think about this a bit from the extension method, but if you present the method from the other side, where people call the static method, it is simpler.

One more thing ... Sometimes you may find yourself (for example, the HtmlHelper in MVC) where you distribute the object outside the convention, and not on the need. This means that it does not matter whether the object that is being distributed is null or not, because the method does not act on it. Although the convention (I suppose) is to throw when the this object is null, I prefer this method to execute normally and document this fact in the help system (ie "... it could be null" or "... null is a valid value for this argument.")