c# - 我应该如何记录我的 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. 在 Project Properties 选项卡的“Comments”组下，单击“NamespaceSummaries”右侧的省略号。
2. 在左上角的复选框列表中，取消选中您要排除的任何命名空间。

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

Answer 2

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

Answer 3

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

你可能认为我知道答案，而我不告诉你是在刻薄。不对。但是我昨晚浏览了文档，看到了关于这个主题的条目。

我不知道你为什么不直接离开 VB 和 C++ 的东西；将来可能会有人在您的库中使用一种（令人震惊的）不是 C#的语言。该语言通常可由帮助查看器设置，因此 C# 开发人员可以忽略 VB 语法。

至于合并，SHFB 具有在任意层次结构中添加任意 HTML 的机制。在 GUI 中，它位于此处：

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

使用它，您可以将 PDF/DOC 转换为 HTML，然后将其嵌入到 .chm 中。