我应该如何记录我的C＃code？ [英] How should I document my C# code?

问题描述

我建立的文档，我们的C＃API包含：

1. 系统概述和当前状态的描述为DOC / PDF文件。
2. 在使用中沙堡.chm文件类库API。

问题：

1. 我应该合并这两个在同一个.chm文件？什么是合并它们的好方法？
2. 我需要排除某些类/包。我怎么可以指定在沙塔？
3. 在它产生的VB code和Visual C ++ code文档。我该如何改变呢？或者我应该离开它，知道我只使用安全code？
4. 在哪里可以找到HTML帮助2.x的浏览器的路径在我的系统？

编辑：

在文档中没有产生我对上面的方法，字段和类的评论。

我应该怎么办？

解决方案

我建议您使用沙堡帮助文件生成器从codePLEX 的。您可以轻松地包含和排除的命名空间，但我不知道该如何去排除单个类。您可以设置选项，只生成公钥/保护类的文档，但我不知道这是否会适合您的方案。

您还可以针对于SHFB特定的语言，你的第二个问题。

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

编辑回应评论：

方向是SHFB 1.8.0.1。我不记得做，在1.7的具体办法，但我相信这是类似的：

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

这也是你把空间摘要屏幕。

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?

解决方案

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.

这篇关于我应该如何记录我的C＃code？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！