C# extension-methods resharper xml-comments

RESHARARPER避免“参数”在XML注释中没有匹配参数。用于扩展方法

发布于 2025-01-21 13:27:12 字数 1069 浏览 3 评论 0原文

我有一类扩展方法，我想对XML良好的评论进行良好的评论。

一个示例功能看起来像这样

/// <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
{
   ...
}

，除了我警告抱怨之外，这一切都很好

参数extendenDobject在[floopmeto]的XML注释中没有匹配参数（但其他参数为）

是不理想的。

现在，我可以评论此参数，但是，它是this参数，因此我方法的消费者永远不会看到它，因此将其添加到XML中只会使呼叫者感到困惑。

我还可以在InvalidxMldOccomment （我将Rider用作IDE）中添加// RESHARPER DISABLE，但是我并不非常热衷于此。它并不能很好地捕获我的意图，也没有指定我要禁用这个非常具体的警告，而希望对XML进行其他警告。

我的问题是，这里是否有更干净的解决方案。当然，不想记录扩展方法的此参数是一个非常常见的用例？

原文

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?

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

夜空下最亮的亮点 2025-01-28 13:27:12

我认为，添加适当的文档以extendedObject也是清洁的，因为您可以在99％的情况下称floopmeto＆lt; t＆gt;（）作为扩展方法，但是您不必。您也可以这样写它：

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

总的来说，我认为最好跟随平台的驾驶领导者，即Microsoft，以防.NET。而且他们倾向于记录此参数，例如在这里。

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.

回复收藏 0 原文

~没有更多了~