c# - XML 注释 - MSDN 文档“注释”部分——你如何复制它？

Question

基本上，在 MSDN 在线帮助中，我经常遇到“注意”部分，但我终生无法弄清楚如何获得相同的输出。显然没有<note>标签。有谁知道如何让这个工作？

IDictionary(TKey, TValue) — 在这个例子中，如果你进入备注部分，你会看到我在说什么。

我正在使用 Sandcastle 帮助文件生成器。

Answer 1

实际上 Sandcastle 和 Sandcastle Help File Builder 都支持一个<note>元素，尽管它隐藏得非常好！:-) 它只记录在我知道的两个地方：

1. 来自 Dyncity的XML 文档评论指南参考...显然不再在网络上提供——该链接曾经是http://www.dynicity.com/downloads/default.aspx。
2. 我在Simple-Talk.com上题为Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code 的文章随附的挂图。请注意，文章中有一个链接可以访问挂图，但它位于文章的最底部，因此我在此处提供了两者的链接。（我的文章中也提到了 Dyncity 的指南；我将与编辑人员沟通，看看他们是否想要托管现在孤立的 Dyncity 指南的本地副本，如果他们愿意，请在此处发布更新。）

这是关于该<note>元素的所有文档。（这来自我的挂图；Dyncity 指南说的基本相同，但不那么简洁。）

令人遗憾的是，我发现的所有文档不足<note>。因此，我进行了快速试用，将每种笔记类型嵌入到备注部分。这是它产生的结果：

---

也就是说，type="caution"在我的特定示例中，您会得到警告图标和标签，而其他两种类型属性值会生成相同的注释图标和标签。我怀疑它的使用可能还有其他方面深埋在灌木丛中。

Answer 2

为了扩展 cubrr 对 Bobby 答案的评论，实际上现在有一些关于 Sandcastle 中 Note 元素的相当广泛的文档。

您可以将四种类别的注释添加到任何其他默认 xml 元素，例如备注或摘要元素。这些是一般、警告、安全或语言。它们之间的主要区别似乎是它们给注释的图标类型以及注释在图标旁边的标题。您可以在此处查看所有这些笔记类型的完整列表。

以下代码为我生成了以下结果：

/// <remarks>
/// <note type="note">
/// This is a note in a remark. It is a General note.
/// </note>
/// <note type="tip">
/// This is a tip note in a remark. It is a General note.
/// </note>
/// <note type="implement">
/// This is a implement note in a remark. It is a General note.
/// </note>
/// <note type="caller">
/// This is a caller note in a remark. It is a General note.
/// </note>
/// <note type="inherit">
/// This is a inherit note in a remark. It is a General note.
/// </note>
/// <note type="caution">
/// This is a caution note in a remark. It is a Cautionary note.
/// </note>
/// <note type="important">
/// This is a important note in a remark. It is a Cautionary note.
/// </note>
/// <note type="security">
/// This is a security note in a remark. It is a Security note.
/// </note>
/// <note type="cs">
/// This is a cs note in a remark. It is a Language note.
/// </note>
/// </remarks>

结果： 生成的帮助文件

Answer 3

关于 Sandcastle 的文档很少，但注释输出可能来自 Sandcastle，而不是 C# 的原生 XML 注释标签。

您可以尝试在要放置注释部分的位置使用以下代码并查看 Sandcastle 输出的内容（以前支持此功能，不确定是否已更改）：

<alert class="note">This is a 'alert class=note'</alert>

有关详细信息，请参阅：Microsoft 帮助标记语言 Longhorn 帮助。