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

Question

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?

Note that the Microsoft documentation always add XML documentation for the this parameters. — Matthew Watson
– Matthew Watson, Commented Apr 15, 2022 at 14:32

mu88 · Accepted Answer · 2022-04-19 08:56:22Z

1

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.

answered Apr 19, 2022 at 8:56

mu88

5,6992 gold badges37 silver badges68 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

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

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related