C# 或 VB 文档注释中的粗体或斜体？答案

【问题标题】：Bold or italic in C# or VB documentation comments?C# 或 VB 文档注释中的粗体或斜体？
【发布时间】：2021-11-03 01:17:40
【问题描述】：

有没有办法在文档 cmets 中使用 bold 或 italic？比如：

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

list of predefined tags 不包含这样的功能，但是您知道一些实现强调/突出显示的方法吗？如果将鼠标悬停在代码上时，它也可以显示在工具提示中。

我们在那里有<c> 和<code>，但它们已经有了它们的语义。

【问题讨论】：

它不是您需要怀疑的 cmets - 任何有效的 XML 在它们中都是可接受的 - 无论是解析生成的 XML 的任何东西，您都需要怀疑，这将允许一些格式化标记。跨度>

标签： c# vb.net visual-studio-2015 roslyn

【解决方案1】：

此功能现已在 Visual Studio 2019 版本 16.3.0 (release notes) 中提供。

您可以将 或 标签用于斜体。
粗体可以使用或标签。
从发行说明来看，似乎支持各种 html 标签，但 official documentation 似乎还没有更新到这个新功能。

看起来像这样：。

【讨论】：

【解决方案2】：

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

不严格，不。但是，Sandcastle（从文档生成 HTML 的文档生成器）支持只在其中使用 HTML，因此如果您使用 Sandcastle 构建它，则可以使用  和 &lt;strong&gt;。

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

Visual Studio 在显示帮助工具提示时会简单地忽略它们：

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

不过，如果您编写了一个供他人使用的库，那么您通常只关心这些。但这也意味着在 IDE 中没有人可以看到您的重点。

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

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

【讨论】：

那么你仍然需要转义它，因为它应该是有效的 XML 内容。
@PatrickHofman：我相当肯定<summary>Some bold text</summary> 是有效的 XML。无需逃避。
对不起，你是对的。我只是想在 cmets 中使用 <，这是不允许的。这些需要被转义，而这些也可能以正确的方式结束。
Joey，你介意用 &lt;strong&gt; 试试 ReSharper 吗？
没有变化，因为它 明确地 告诉它只是文字字符。与 Javadoc 不同，XML 文档不包含输出是 HTML 的含义。因此，在这种情况下不是。 Java IDE 通常会呈现带有呈现 HTML 的 Javadoc，但这是意料之中的。

【解决方案3】：

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

 - 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

纯文本是老式的，但它可能非常有效 - 并且在技术发生变化后很长一段时间内仍然有效。

【讨论】：

谢谢，是的，但是如果我想添加文本“根据 ReadAllFiles 和 PreserveTimestamp 设置返回值”，这些强调方式是用处不大，它们会使文本的可读性降低。
很少有人为其他程序员编写适当的文档。你的所作所为令人钦佩。

【解决方案4】：

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

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

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

【讨论】：

不需要插件吗？在 Visual Studio 2015 中是否已经可以实现？
对不起@miroxlav，我并不是说 Visual Studio 会理解 wiki 标记。那只是一个约定。

【解决方案5】：

添加对上述已接受答案的说明（“此功能现已在 Visual Studio 2019 版本 16.3.0 中提供”https://stackoverflow.com/a/58227889/17203657）

来自发行说明 (https://docs.microsoft.com/en-us/visualstudio/releases/2019/release-notes-v16.3#net-productivity-163P1) '现在提供对 XML cmets 的快速信息 样式支持。'

快速信息是当您将鼠标悬停在方法（它不是 Intellisense）上时，它支持粗体、斜体。

IntelliSense 是当您向方法添加参数时显示的内容，它不支持粗体、斜体。

从 VS 16.11.5 开始，我还没有找到向 IntelliSense 视图添加粗体或斜体的方法。

注意：我没有足够的积分将其添加为评论。

【讨论】：

【解决方案6】：

当我遇到（请参阅 here）时，我正试图在 Intellisense 显示中添加换行符，它插入（根据文档）可点击的文档参考。我还没有弄清楚如何单击 Intellisense 工具提示，但它确实提供了一个类型格式化/彩色显示，可以帮助您的参考脱颖而出（请注意，该参考必须对 Intellisense 可用）。

旁注：我从来没有弄清楚如何进行单行换行。我能得到的最接近的是双换行符，使用标签...

【讨论】：