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

问题描述

我经常使用 XML 文档来记录我的类、方法和属性，但请查看 Microsoft 的此方法:

用法?这是什么魔法?如何模仿这种魔法?

源代码中没有这样的东西，我检查了(.Net 4.5).它也没有 xmldoc 标记，它不应该存在，但它显示在工具提示中.

我不久前注意到了它，但没有时间进行调查，所以现在我有，而且我浪费了至少一个小时试图徒劳地弄清楚.

这是一件好事，因为它显示在工具提示中.我们确实有 <example> 标签，但不是这样，这是一个完全不同的野兽.

解决方案

我能找到的只有

这两种方法都会在弹出窗口中获取Usage 部分，没有任何xml 注释.所以这里提醒开发者不要忘记等待Tasks.

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屋！