神秘的“用法”是指Visual Studio文档XML注释标签中的标签 [英] The Mysterious "usage" Tag in Visual Studio Documentation XML Comment Tags

问题描述

我经常使用XML文档来记录我的类，方法和属性，但从Microsoft看一下这种方法：

用法？这是什么魔法？

我检查了源代码中没有这样的东西（.Net 4.5）。

我注意到它有一段时间了，但是还没有，它没有xmldoc标签，它也不应该存在，但是它显示在工具提示中。是时候进行调查了，所以现在我有了，我浪费了至少一个小时来徒劳地弄清楚。

这是一件好事，因为它显示在工具提示中。我们确实有< example> 标记，但事实并非如此，这完全是另一种野兽。

解决方案

我能找到的只是

这两种方法都将获得用法弹出窗口中的部分，没有任何xml注释。因此，这提醒开发人员不要忘记等待 Task s。

I often use XML documentation to document my classes, methods and properties but take a look at this method from Microsoft:

Usage? What kind of sorcery is this? How does one emulate this wizardry?

There's no such thing in the source code, I checked (.Net 4.5). There's no xmldoc tag for it either, it isn't supposed to exist and yet it shows up in the tooltip.

I noticed it a while back but haven't had time to investigate so now I had and I wasted at least an hour trying to figure it out in vain.

It's a nice thing because it shows up in tooltips. We do have the <example> tag but that's not it, this is a different beast entirely.

解决方案

All I can find is the <code> element, but it doesn't provide such neat output as one at the image.

It looks like it's hardcoded to Task static methods somewhere inside the Visual Studio: reference code and github do not contain such xml comments, and I didn't find any other methods with such Usage thing, even the async ones.

Maybe it's a part of Visual Studio support for async/await syntax, notifying the developer to not forget to await the created task.

Update: I think that this is a Visual Studio behavior. Consider such code:

public static Task<int> TestMethod1()
{
    return Task.FromResult(9);
}

public static async Task<int> TestMethod2()
{
    return await Task.FromResult(9);
}

Both of such methods will get the Usage section in pop-up, without any xml comments. So this is a reminder for developer to not forget to await the Tasks.

这篇关于神秘的“用法”是指Visual Studio文档XML注释标签中的标签的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！