我应该如何记录我的c#代码?

I am building the documentation for our C# API containing:

我正在为我们的c# API构建文档，其中包含:

A general overview and description of the current state as a doc/pdf file.
当前状态作为doc/pdf文件的概述和描述。
A class library API in a .chm file using Sandcastle.
使用Sandcastle的.chm文件中的类库API。

Questions:

Should I merge these two into the same .chm file? What is a good way to merge them?
我应该将这两个文件合并到相同的.chm文件中吗?什么是合并它们的好方法?
I need to exclude certain classes/packages. How can I specify that in SandCastle?
我需要排除某些类/包。如何在SandCastle中指定呢?
It generates documentation for the VB code and the Visual C++ code. How can I change this? Or should I leave it, knowing that I am only using safe code?
它为VB代码和Visual c++代码生成文档。我怎样才能改变这个呢?或者我应该离开它，知道我只使用安全代码?
Where can I find HTML Help 2.x Viewer Path on my system?
我在哪里可以找到HTML帮助2。x查看器路径在我的系统上?

Edit:

The comments I make above methods, fields and classes are not generated in the documentation.

上述方法、字段和类的注释在文档中没有生成。

What should I do?

我应该做什么?

3 个解决方案

#1

I recommend that you use Sandcastle Help File Builder from Codeplex. You can easily include and exclude namespaces, but I am unsure how to go about excluding a single class. You can set the option to only generate documentation for public/protected classes, but I do not know if that will fit your scenario.

我建议您使用来自Codeplex的Sandcastle帮助文件构建器。您可以很容易地包含和排除名称空间，但是我不确定如何排除单个类。您可以设置选项，只生成公共/受保护类的文档，但我不知道这是否适合您的场景。

You can also target a specific language in SHFB, as to your second question.

关于你的第二个问题，你也可以在SHFB中找到一种特定的语言。

Additionally, you can use MAML within SHFB for conceptual documentation, such as you mention as being in the doc/pdf file. You should be able to use Doc2Maml for to migrate your existing documentation. Doc2Maml is a part of DocProject, but it appears that you might be able to run it standalone.

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

Edit in response to comment:

编辑回应评论:

Directions are for SHFB 1.8.0.1. I do not remember the exact way to do it in 1.7, but I believe it is similar:

方向为SHFB 1.8.0.1。我不记得确切的方法在1.7，但我相信它是相似的:

Under "Comments" group in the Project Properties tab, click the ellipsis to the right of "NamespaceSummaries".
在“项目属性”选项卡的“Comments”组下，单击“NamespaceSummaries”右边的省略号。
In the checkbox list in the top left, uncheck any namespace you want to exclude.
在左上角的复选框列表中，取消选中要排除的任何名称空间。

This is also the screen where you put namespace summaries in.

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

#2

In addition to Sand Castle as mentioned above, I would also recommend looking at FxCop and StyleCop to help make sure your code and documentation is up to CLS Compliance standards.

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

#3

Sandcastle Help File Builder (SHFB) itself has a .chm file where you can find the answers to questions like "how can I exclude certain namespaces or classes from the generated doc?"

Sandcastle Help File Builder (SHFB)本身就有一个.chm文件，您可以在其中找到诸如“如何从生成的doc中排除某些名称空间或类?”

You may think I know the answer and I am being snarky by not telling you. Not true. But I was skimming the doc last night and saw an entry on this very topic.

你可能认为我知道答案，但我不告诉你，我就会生气。不正确的。但是我昨晚浏览了一下博士的文章，看到了一个关于这个话题的条目。

I don't know why you wouldn't just leave in the VB and C++ stuff; there may in the future be someone who uses a language that is (shockingly) not C# with your library. The language is normally settable by the help viewer, so C# devs can ignore the VB syntax.

我不知道你为什么不把它放在VB和c++中;将来可能会有人在您的库中使用(令人震惊的)不是c#的语言。该语言通常由帮助查看器设置，因此c# devs可以忽略VB语法。

As for merging, SHFB has a mechanism to add in arbitrary HTML in an arbitrary hierarchy. In the GUI it is here:

至于合并，SHFB有一种在任意层次结构中添加任意HTML的机制。在GUI中是这样的:

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

Using this, you could convert the PDF/DOC to HTML and then just embed it in the .chm.

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

#1