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

Question

有没有办法在文档注释中使用粗体或斜体？类似的东西：

 

f = ArticleForm(data=request.POST)

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

我们有/// <summary>Cleanup method. This is <b>recommended</b> way of cleanup.</summary> public void CleanAll(); 和<c>，但他们已经有了语义。

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

Visual Studio 2019版本16.3.0（release notes）中现已提供此功能。

• 您可以将public static class ColumnExtensions { public static void SaveAsCsv(this List<Column> columns, string filePath) { File.WriteAllText(columns.ToCsv(), filePath); } public static string ToCsv(this List<Column> columns) { var csv = new StringBuilder(); // Write as an expression or simply //csv.AppendCsvHeader(nameof(Item.TimeStamp)); csv.AppendCsvHeader<string, DateTime>(x => columns.First().ItemList.First().TimeStamp); for (var index = 0; index < columns.Count; index++) { var column = columns[index]; // Most csv readers don't care if you have a "," at the end of the line. But for completeness we avoid doing that. // It makes the code a bit more complicated though. You can ignore this you want. csv.AppendCsvHeader(column.ColName, index == columns.Count - 1); } csv.AppendLine(); for (var i = 0; i < columns[0].ItemList.Count; i++) { csv.AppendCsvField(columns[0] .ItemList[i] .TimeStamp.ToString("yyyy/MM/dd HH:mm:ss")); for (var index = 0; index < columns.Count; index++) { var column = columns[index]; csv.AppendCsvField(column.ItemList[i] .Value.ToString("N"), index == columns.Count - 1); } csv.AppendLine(); } return csv.ToString(); } } public static class CsvExtensions { private const string Delimiter = ","; private static string AsCsvFriendly(this string val) { return val?.Replace(",", ";") ?? string.Empty; } private static string AddDelimiterIfRequired(bool withoutDelimiter) { return withoutDelimiter ? string.Empty : Delimiter; } public static void AppendCsvField(this StringBuilder stringBuilder, string value, bool withoutDelimiter = false) { stringBuilder.Append($"{value.AsCsvFriendly()}{AddDelimiterIfRequired(withoutDelimiter)}"); } public static void AppendCsvHeader(this StringBuilder stringBuilder, string value, bool withoutDelimiter = false) { stringBuilder.Append($"{value.AsCsvFriendly()}{AddDelimiterIfRequired(withoutDelimiter)}"); } public static void AppendCsvHeader<TIn, TOut>(this StringBuilder stringBuilder, Expression<Func<TIn, TOut>> f, bool withoutDelimiter = false) { stringBuilder.Append($"{(f.Body as MemberExpression)?.Member.Name}{AddDelimiterIfRequired(withoutDelimiter)}"); } } 或<i>标签用于斜体。
• 您可以将<em>或<b>标签用于粗体。
• 从发行说明中看，似乎支持各种html标记，但是official documentation似乎尚未使用此新功能进行更新。

它看起来像这样：。

Answer 3

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

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

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

Answer 4

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

 - 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 5

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

侧面说明：我从未弄清楚如何进行单个换行。我能得到的是使用标记的双换行符...