C#文档 对于一个类的<example><code>...</code></example>

Question

我有一个类，想创建一个简单的示例来演示如何使用它。然而，当我在类声明中使用<example>标签时，示例不会出现在Sandcastle输出中。对于对象的成员，它可以正常工作，但对于类本身则无效。请问Sandcastle能否处理这种情况？

我想要做的事情举例如下： MSDN TcpClient 文档 其中包含了一个关于如何使用该类的示例。我该如何为我的类添加类似的内容？ 我想要做的是：

/// <summary> My example class </summary>
/// <example>
///   <code>
///      // Example code on how to use the class
///   </code>
/// </example>
public class MyClass
{
    public string MyString {get;set;}
}

- galford13x

---

不清楚沙堡，但Monodoc和Doxygen可以为我提供这方面的示例。 - IanNorton

你的示例应该根据MSDN正常工作。 - BlueM

确实如此，通常我应该给出一个更具代表性的例子或实际代码。不幸的是，我所编写的系统无法连接到外部网络，因此需要我从头开始编写任何问题。 - galford13x

提示。查看 <![CDATA[ .. ]]> 标签 http://www.w3schools.com/xml/xml_cdata.asp 和 https://dev59.com/73E85IYBdhLWcg3wbS1h - John Alexiou

Answer 1

对于Sandcastle，可以通过修改main_sandcastle.xslt文件中的自定义标签来创建自定义标签转换定义。您可能感兴趣的文件包括：

transforms/main_sandcastle.xslt content/shared_content.xml

- ideafountain

---

这非常有趣，我没有意识到Sandcastle有那个功能。谢谢你的提示！ - galford13x

Answer 2

由于示例包含泛型，文档未正确解析，我不得不用<替换所有的<，用>替换所有的>。

我已经通过在文档示例中放置“this is a test”来测试文档，并且它可以正常工作，但由于某种原因，在我的实际代码中它却不能正常工作。在使用适当的转义序列替换标记后，一切都正常了。

还要注意，所声称的{T}也没有正常工作，因为它被直接打印而不是转换为通用语句。虽然我希望在<code></code>语句中看到这一点，但我也希望List<string>声明也能正常工作。

- galford13x

---

澄清一下：Xml文档注释是嵌入在代码注释中的XML片段。它必须是有效的XML - 因此，正如您发现的那样，在doc条目的文本中的任何<都需要表示为XML实体，<（对于其他字符如>，＆等也是如此）。即使在<code>块内，这些字符也需要表示为实体，以便可以正确解析XML。（还要确保每个<tag>都用相应的</tag>关闭）。如果在intellisense或sandacastle中出现注释块丢失的问题，请检查xml语法错误。 - Jason Williams

@Jason：这确实有道理。如果解析器忽略XML标记，它将如何知道代码段何时结束。这就需要某种转义序列，这就是<提供的内容。我想，如果{T}在特殊情况下的标签中（如<see cref="" />）起作用，那么它也会在<code>标签中起作用，但我想这也将限制括号的使用。 - galford13x