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

问题描述

我正在构建我们的C＃API文档，其中包含：

1. 将当前状态作为doc / pdf的一般概述和说明文件。


2. 使用Sandcastle的.chm文件中的类库API。

问题：

1. 我应该合并这两个进入同一个.chm文件？什么是合并他们的好方法？


2. 我需要排除某些类/包。如何在SandCastle中指定？


3. 它生成VB代码和Visual C ++代码的文档。我该怎么改？或者我应该离开它，知道我只使用安全的代码？


4. 我在哪里可以找到我的系统上的HTML Help 2.x Viewer Path？

编辑：

我在上述方法，字段和类不在文档中生成。

我该怎么办？

解决方案

p>我建议您从Codeplex使用沙堡帮助文件生成器。您可以轻松地包含和排除命名空间，但我不确定如何排除单个类。您可以将选项设置为仅生成公共/受保护类的文档，但不知道是否符合您的方案。

您还可以将特定语言定位到SHFB，关于您的第二个问题。

此外，您可以在SHFB中使用MAML进行概念性文档，例如您在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＃代码？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！