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

Question

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

IDictionary(TKey, TValue) — 在此示例中，如果您进入备注部分，您会看到我在说什么。

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

Answer 1

实际上，Sandcastle 和 Sandcastle 帮助文件生成器都支持 <note> 元素，尽管它隐藏得非常好！ :-) 它只记录在我知道的两个地方：

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

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

遗憾的是，我发现的关于<note> 的所有文档不足。所以我进行了快速试验，将每种笔记类型嵌入到 Remarks 部分。这是它产生的结果：

---

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

Answer 2

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

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

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

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

结果： Generated Help File

Answer 3

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

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

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

请参阅：Microsoft Assistance Markup Language Longhorn Help 了解更多信息。