Resharper avoid "Parameter has no matching param in the XML comment" for extention methods

user_7711148 0
Viewed 131

I have a class of extension methods which I want to have good XML comments for.

An example function looks like this

/// <summary>
/// Does something cool and assigns the result to <paramref name="componentVariable"/>.
/// Logs if component cannot be flooped.
/// </summary>
/// <param name="componentVariable">The variable to hold the component</param>
/// <typeparam name="T">The type of the component to be flooped</typeparam>
/// <exception cref="NullReferenceException">Throws if component cannot be found.</exception>
public static void FloopMeTo<T>(this Foo extendedObject, out T componentVariable) where T : Component
{
   ...
}

This all works great, except I get a warning complaining that

Parameter extendedObject has no matching param in the XML comment for [FloopMeTo] (but other parameters do)

Which is not ideal.

Now I could comment this parameter, however, it's a this parameter so the consumer of my method will not ever see it so adding it to the XML would only confuse the caller.

I could also add a // ReSharper disable once InvalidXmlDocComment(I'm using Rider as an IDE) but this solution I'm not super keen on. It doesn't really capture my intent very well and doesn't specify that I want to disable this one very specific warning but want other warnings about the XML.

My question is, is there a cleaner solution here. Surely It's a very common use case to not want to document the this parameter of an extension method?

xml-comments extension-methods resharper c#
1 Answers

I would argue that it's cleaner to add proper documentation for extendedObject as well because you might call FloopMeTo<T>() as an extension method in 99% of all cases, but you don't have to. You could also write it like this:

var myExtendedObject = new Foo();
YourClass.FloopMeTo<string>(myExtendedObject, out string temp);

And in general I think it's a good practice to follow the driving leaders of a platform, i. e. Microsoft in case of .NET. And they tend to document the this parameters as well, for example here.

user_49195260
Related