我该如何记录我的C＃代码？

Question

我正在为包含以下内容的C＃API构建文档：

1. 作为doc / pdf文件的当前状态的一般概述和描述。
2. 使用Sandcastle的.chm文件中的类库API。

问题：

1. 我应该将这两个合并到同一个.chm文件中吗？合并它们的好方法是什么？
2. 我需要排除某些类/包。如何在SandCastle中指定它？
3. 它生成VB代码和Visual C ++代码的文档。我怎么能改变这个？或者我应该离开它，知道我只使用安全代码吗？
4. 我在哪里可以找到系统上的HTML Help 2.x Viewer Path？

编辑：

我在文档中没有生成上面方法，字段和类的注释。

我该怎么办？

Answer 1

我建议您使用Codeplex中的Sandcastle Help File Builder。您可以轻松地包含和排除名称空间，但我不确定如何排除单个类。您可以将选项设置为仅生成公共/受保护类的文档，但我不知道这是否适合您的方案。

对于第二个问题，您也可以在SHFB中定位特定语言。

此外，您可以在SHFB中使用MAML作为概念文档，例如您在doc / pdf文件中提到的。您应该可以使用Doc2Maml来迁移现有文档。 Doc2Maml是DocProject的一部分，但似乎您可以独立运行它。

编辑以回复评论：

指示适用于SHFB 1.8.0.1。我不记得1.7中的确切方法，但我相信它是相似的：

1. 在“项目属性”选项卡的“注释”组下，单击“NamespaceSummaries”右侧的省略号。
2. 在左上角的复选框列表中，取消选中要排除的任何命名空间。

这也是您将名称空间摘要放入的屏幕。

Answer 2

除了上面提到的Sand Castle之外，我还建议您查看FxCop和StyleCop，以确保您的代码和文档符合CLS合规性标准。

Answer 3

Sandcastle帮助文件生成器（SHFB）本身有一个.chm文件，您可以在其中找到“如何从生成的文档中排除某些名称空间或类？”等问题的答案。

你可能认为我知道答案，而且我没有告诉你，我很讽刺。不对。但我昨晚在浏览文档时看到了这个话题。

我不知道为什么你不会留下VB和C ++的东西;未来可能会有人使用与您的图书馆（令人震惊）而不是C＃的语言。该语言通常可以由帮助查看器设置，因此C＃devs可以忽略VB语法。

对于合并，SHFB具有在任意层次结构中添加任意HTML的机制。在GUI中，它在这里：

http://www.freeimagehosting.net/uploads/7de19ea568.jpg

使用此功能，您可以将PDF / DOC转换为HTML，然后将其嵌入.chm。