Question

我今天第一次使用SandCastle和HelpBuilder GUI来帮助创建一些我们公开的函数和属性的API。我已将/// <summary> ... </summary包含在许多属性中，我觉得他们会从额外的文档或使用示例中受益。

当我将输出文件构建到chm时，我根本没有看到摘要描述。列出了所有属性成员，但其描述为空白。我重建了这个项目，并在SandCastle中尝试了一些不同的设置，但它们仍然没有显示出来。

我有什么明显的东西可以忽略吗？ SandCastle没有阅读财产摘要吗？或者摘要需要不同的关键字吗？

Answer 1

您必须告诉Visual Studio在编译时生成XML文档文件：只需按照此处所述设置相应的项目属性： http://msdn.microsoft.com/en-us/library/vstudio/x4sa0ak0(v=vs.100).aspx

之后，Sandcastle将输出＆＃34;摘要＆＃34;评论＆＃34;描述＆＃34;列。

Answer 2

来自Sandcastle Common Issues帮助页面：

文档中缺少代码注释

默认情况下，项目的所有XML文档都应位于名为comments.xml的单个文件中。如果您有多个XML文档文件，则将它们放在名为“注释”的新文件夹中，并调整sandcastle.config以使用通配符，如下例所示。

<!-- Copy in comments -->
<component type="Microsoft.Ddue.Tools.CopyFromIndexComponent"
           assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
  <index name="comments" value="/doc/members/member"
         key="@name" cache="100">
    <data base="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727"
          recurse="false" files="*.xml" />

    <data files="Comments\*.xml" />  <!-- This line was modified -->

  </index>
  <copy name="comments" source="*" target="/document/comments" />
<components>

有关详细信息，请参阅this blog post。

Answer 3

看起来另一个答案已被接受为有效，但我会添加我的解决方案，因为我遇到了同样的问题，但出于其他原因。

如果您打开用作文档源的XML文件，请控制您为其编写注释的方法/属性，但不会显示在最终的sandcastle文档中。如果您看到消息：

对成员＆＃34; M：...

忽略了错误形成的XML注释

然后，像我一样，你可能包含了一些XML并不高兴的字符。我使用了＆＃34;＆amp;＆＃34;在评论中，如果您使用＆＃34;＆lt;＆＃34;或＆＃34;＆gt;＆＃34;同样。修复你的评论，你应该好好去！

Sandcastle没有记录财产摘要

3 个答案: