C#或VB文档注释中的粗体还是斜体？

Question

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

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

预定义标签列表不包含此类功能,但您是否知道实现强调/突出显示的某种方式？优选地,如果在悬停在代码上时也可以在工具提示中显示.

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

Answer 1

不严格,没有.但是,Sandcastle(从文档生成HTML的文档生成器)支持在那里使用HTML,所以如果使用Sandcastle构建它,您可以使用<em>并且<strong>很好.

换句话说:正如Jamiec已经指出的那样,XML文档注释只是XML.所以你可以在那里放置任何有效的XML; 编译器很乐意将其写入文档XML文件.这一切都取决于处理该文件的软件.Sandcastle只是将它不知道的任何内容传递给HTML,因为无论如何这都是它的输出格式.

显示帮助工具提示时,Visual Studio将忽略它们:

ReSharper在其Ctrl+ Q视图中将HTML标记显示为文本,这使得事情有点难看:

但是,如果您创建一个供其他人使用的库,那些通常只会引起您的关注.但这也意味着在IDE中没有人能够按照预期看到你的重点.

在编写API文档时,我发现实际上没有必要强调; 通常情况下,你可以用不同的方式写一个句子,或者重新构造一个单独的段落中的重要节点,而不需要强调.一致的语言和措辞也有助于读者在习惯之后获取重要的笔记.

你的代码可能只是一个例子,但我认为摘要最需要强调,因为它只注意 - 在一个简短的句子中 - 类型是什么或方法做什么.如果有的话,请在备注中使用它,即使这样,我也会仔细考虑你是否真的需要它.

Answer 2

还有其他增加强调的方法：

 - 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

纯文本是老派的做法，但它可能非常有效 - 并且在技术发生变化后很长时间内仍能发挥作用。

Answer 3

Visual Studio 2019版本16.3.0（发行说明）现在提供了此功能。

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

看起来像这样： 。