How should I document my C# code?

Question

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

1. A general overview and description of the current state as a doc/pdf file.
2. A class library API in a .chm file using Sandcastle.

Questions:

1. Should I merge these two into the same .chm file? What is a good way to merge them?
2. I need to exclude certain classes/packages. How can I specify that in SandCastle?
3. 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?
4. Where can I find HTML Help 2.x Viewer Path on my system?

Edit:

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

What should I do?

Answer 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.

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

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.

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:

1. Under "Comments" group in the Project Properties tab, click the ellipsis to the right of "NamespaceSummaries".
2. 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.

Answer 2

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?"

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.

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

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

Answer 3

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.

Answer 4

SandCastle don't have a Getting Started help.

Try to use NDoc.

Here is the NDoc Help