我的团队负责为我们编写的大型系统开发 API。我们需要提供示例代码，以便其他使用我们 API 的开发人员可以学习如何使用它。我们一直在使用 xml 文档注释记录代码。例如。
/// <summary>Summary here</summary>
/// <example>Here is an example <code>example code here</code> </example>
public void SomeFunction()
然后我们使用 Sandcastle 并构建我们需要的帮助文件（chm 和一个在线网站）。
当示例代码不起作用时，这是相当尴尬的，这通常是因为某些功能发生了变化或一个简单的错误。
有没有人做过这样的事情，而且还配置了单元测试以在示例代码上运行，以便知道它们在构建期间可以工作？
我建议在您的 XML 中使用一个特殊的标记，上面写着“从这个地方获取代码示例”。它将引用可以通过单元测试运行的普通 C# 文件。举个例子，你可能有：
/// <summary>Summary here</summary>
/// <example>Here is an example
/// <code>!!sourcefile:SomeClassTest.cs#SomeFunction!!</code></example>
public void SomeFunction()
您的单元测试正常运行，然后在“创建 XML”和“运行 Sandcastle”之间插入一个构建步骤，您将用适当的内容替换每个“文件令牌”。您甚至可以在文档生成时将挂钩放入 Sandcastle 以执行此操作 - 我对 Sandcastle 的了解还不够，无法确定。
发明自己的标记当然很难看，但它应该可以工作。
当然，这假设代码示例很容易进行单元测试——有些可能不是（如果它们正在处理资源等）。至少你会知道它可以编译:)
是的，sandcastle 支持这一点，保持示例的正确性非常好。您可以像这样指向代码区域：
/// <summary>
/// Gizmo which can act as client or server.
/// </summary>
/// <example>
/// The following example shows how to use the gizmo as a client:
/// <code lang="cs"
/// source="..\gizmo.unittests\TestGizmo.cs"
/// region="GizmoClientSample"/>
/// </example>
public class Gizmo
然后，您可以使用 TestGizmo.cs 中的一些测试代码作为示例，将其包含在一个区域中：
[Test]
public GizmoCanActAsClient()
{
#region GizmoClientSample
Gizmo gizmo = new Gizmo();
gizmo.ActAsClient();
#endregion
}
警告：如果您移动或重命名测试文件，则只有在您尝试使用 sandcastle 重新生成文档时才会收到错误消息。
简单的解决方案： 制作一个包含所有示例代码头的小型应用程序，然后调用它们各自的入口点
#include "samples/sampleA.h"
void main()
{
SomeFunction();
}
然后在构建运行这些小应用程序之后，您需要确保它们运行正常。但是，您能否在没有人与 NightlyBuild 服务器举行睡衣派对的情况下验证代码是否正常运行？
更好的解决方案：记录输出并让某人在早上查看它。
更好的解决方案：记录输出并 grep 或其他东西，这样除非它坏了，否则没有人需要查看它。
最佳解决方案：找到一个合适的测试框架，希望能得到所有花里胡哨的东西，这样它就可以在它坏了或类似的情况下给人们发电子邮件。在我们的例子中，我们避免了花里胡哨的东西，而是连接了一个USB 警笛，当有什么东西发生故障时它会响起。这非常令人兴奋！
我自己没有这样做，但我在实用程序员书籍中看到过这一点。如果我没记错的话，“使用 Nunit 在 C# 中进行实用单元测试”一书提到他们为这本书做了这个。不过，可能是他们在其中一个播客中提到过。
他们提到他们为他们的书籍设置了一个持续构建服务器。如果我没记错的话，他们使用乳胶或其他一些基于文本的标记来编写他们的书，并且他们有构建步骤来格式化书中的标记以及构建和单元测试代码。