vb.net C# 或 VB 文档注释中的粗体或斜体？

Bold or italic in C# or VB documentation comments?

提问by miroxlav

Is there a way to use boldor italicinside documentation comments? Something like:

有没有办法在文档注释中使用粗体或斜体？就像是：

/// <summary>Cleanup method. This is <b>recommended</b> way of cleanup.</summary>
public void CleanAll();

List of predefined tagsdoes not contain such a features, but do you know of some way of achieving emphasis/highlighting? Preferably, if it could be shown also in tooltips when hovering over the code.

预定义标签列表不包含这样的功能，但是您知道某种实现强调/突出显示的方法吗？如果将鼠标悬停在代码上时它也可以显示在工具提示中，则最好。

We have <c>and <code>there, but they already have their semantics.

我们<c>和<code>那里，但他们已经有了自己的语义。

采纳答案by Batesias

This feature is now available in Visual Studio 2019 version 16.3.0 (release notes).

此功能现已在 Visual Studio 2019 版本 16.3.0（发行说明）中可用。

• You can use the <i>or <em>tags for italic.
• You can use the <b>or <strong>tags for bold.
• From the release notes, a variety of html tags seem to be supported, but the official documentationdoesn't seem to be updated with this new feature just yet.

• 您可以将<i>或<em>标签用于斜体。
• 您可以将<b>或<strong>标记用于粗体。
• 从发行说明来看，似乎支持各种 html 标签，但官方文档似乎尚未使用此新功能进行更新。

It looks like this: .

它看起来像这样：。

回答by Joey

OP's note: This was the accepted answer before 2019 Visual Studio update after which I accepted the other answer. This one is still useful and valid for users without that update.

OP 的注释：这是 2019 年 Visual Studio 更新之前接受的答案，之后我接受了另一个答案。对于没有该更新的用户，这个仍然有用且有效。

---

---

Not strictly, no. However, Sandcastle(a documentation generator that generates HTML from the documentation) supports to just use HTML in there, so you can use <em>and <strong>just fine if you build it with Sandcastle.

不严格，没有。但是，Sandcastle（一个从文档中生成 HTML 的文档生成器）支持只在其中使用 HTML，因此如果您使用 Sandcastle 构建它，您就可以使用<em>并且<strong>很好。

To put it another way: As Jamiecalready notes, XML documentation comments are just XML. So you can put any valid XML in there; the compiler will happily write that into the documentation XML file. It all depends on the software that processes that file. Sandcastle just passes anything it doesn't know on as HTML, since that's its output format anyway.

换句话说：正如Jamiec已经指出的那样，XML 文档注释只是 XML。因此您可以将任何有效的 XML 放入其中；编译器很乐意将其写入文档 XML 文件中。这完全取决于处理该文件的软件。Sandcastle 只是将它不知道的任何内容作为 HTML 传递，因为无论如何这是它的输出格式。

Visual Studio will simply ignore them when displaying the help tooltip:

Visual Studio 将在显示帮助工具提示时忽略它们：

ReSharper in its Ctrl+Qview will show HTML tags as text which makes things a bit ugly:

ReSharper 在其Ctrl+Q视图中会将 HTML 标签显示为文本，这让事情变得有点难看：

Those are usually only of concern to you if you author a library to be used by others, though. But it also means that within the IDEno one can see your emphasis as intended.

但是，如果您编写了一个供其他人使用的库，这些通常只会引起您的注意。但这也意味着在 IDE 中，没有人可以按预期看到您的重点。

I have found actually little need for emphasis when writing API documentation; oftentimes you can write a sentence differently or restructure to have important nodes in a separate paragraph near the end, to not need emphasis at all. Consistent language and phrasing also helps readers to pick up important notes once they're used to it.

我发现在编写 API 文档时实际上几乎不需要强调；通常你可以用不同的方式写一个句子，或者重组在靠近结尾的单独段落中包含重要的节点，根本不需要强调。一致的语言和措辞还可以帮助读者在习惯后捡起重要的笔记。

Your code probably just was an example, but I think the summaryneeds emphasis least of all since it only notes – in a short sentence – what a type is or a method does. If anything, use it in the remarks and even then I'd carefully consider whether you actually need it.

您的代码可能只是一个示例，但我认为摘要最不需要强调，因为它只用一个简短的句子说明了类型或方法的作用。如果有的话，请在备注中使用它，即便如此，我也会仔细考虑您是否真的需要它。

回答by Antoni

An alternate way is to use a wiki markup-like style instead.

另一种方法是使用类似 wiki 标记的样式。

/// <summary>Cleanup method. This is *recommended* way of cleanup.</summary>
public void CleanAll();

Edit 1:AFAIK Visual Studio doesn't understand wiki markup. I was just suggesting to use wiki markup as a convention. Your team would still see the raw (unformatted) wiki markup in the method's intellisense.

编辑 1：AFAIK Visual Studio 不理解 wiki 标记。我只是建议使用 wiki 标记作为约定。您的团队仍会在方法的智能感知中看到原始（未格式化）的 wiki 标记。

回答by Antoni

There are other ways of adding emphasis:

还有其他增加重点的方法：

 - Upper case:    some BOLD text       // you are shouting, but they WILL read it
 - First letter:  some Bold text       // less emphasis
 - Asterisks:     some **bold** text   // 2 asterisks seem to work best
 - Dashes:        some --bold-- text   // less emphasis

Plain text is old-school, but it can be very effective - and works long after the technology has changed.

纯文本是过时的，但它可以非常有效 - 并且在技术改变后很长一段时间内仍然有效。

回答by G Cook

I was trying to add a line break into the Intellisense display when I came across <see cref="YourReferenceHere"/> (see here), which inserts (according to the documentation) a clickable reference into the documentation. I have not figured out how to click on Intellisense tooltips, but it does provide a type-formatted/colored display which helps your reference to stand out (note that the reference must be available to Intellisense).

当我遇到 <see cref=" YourReferenceHere"/> （参见此处）时，我试图在 Intellisense 显示中添加换行符，这将（根据文档）插入到文档中的可点击引用。我还没有弄清楚如何点击 Intellisense 工具提示，但它确实提供了一个类型格式/彩色显示，可以帮助您的参考脱颖而出（请注意，该参考必须可供 Intellisense 使用）。

Side Note: I never did figure out how to do a single line break. Closest I can get is a double line break, using the <para/> tag...

旁注：我从来没有想过如何做一个换行符。我能得到的最接近的是一个双换行符，使用 <para/> 标签......