Visual Studio 2010中所有注释的文档

Question

如何在Visual Studio 2010中使用C#语言从所有类、方法和属性注释创建文档？

- ARZ

---

这个文档会是什么样子？ - Michael Petrotta

包含了所有与解决方案对象相关的注释。 - ARZ

你如何注释一个属性？ - TrueWill

你想让你的属性使用被记录下来，有特别的原因吗？ 就目前为止，我的文档编写如下： 该属性在类的注释中进行了描述。在文档中，您会看到该类/属性/方法被标记了属性。因此，您将拥有一个直接链接。 如果您希望读者获取更多关于使用的信息，可以使用“备注”部分。 - oberfreak

Answer 1

尝试使用Sandcastle和Sandcastle Helpfile Builder。它可以创建CHM文件、MSHelp文件或者MSDN风格的HTML页面。这个工具非常易于使用，可以加载解决方案文件。
Sandcastle Helpfile Builder: http://shfb.codeplex.com/
仅限Sandcastle: http://sandcastle.codeplex.com/

- oberfreak

Answer 2

您可以使用Sandcastle创建类似于MSDN的文档。

- Henrik

Answer 3

Doxygen可以根据您代码中的注释生成漂亮的HTML文档，只要您遵循几个简单的格式规则即可。请参考：Doxygen官网。

- Miguel Grinberg

Answer 4

首先值得一提的是，你想要记录API库的文档，以便他人（甚至是未来的你:-)）能够在不必阅读代码的情况下使用你的代码，这是值得赞扬的。这本身就是一个很大的进步！

有许多工具可以帮助自动化此任务，特别是Doxygen和Sandcastle，正如其他人之前提到的那样。我没有使用过Doxygen，因此我将限制我的评论在Sandcastle上。由Microsoft提供的Sandcastle是一个很好的起点，但显然很难使用，因此许多积极的独立开发者在Sandcastle之上构建了更易用的界面。其中最重要的是Sandcastle Help File Builder (SHFB)。通过SHFB的GUI，您“简单地”创建一个Sandcastle项目，根据您的喜好设置项目属性，然后将您的文档集构建为网站或CHM文件或其他几种格式。

我在上面加了引号的简单一词，因为在SHFB中工作只是你面前任务的一小部分——更广泛的任务是用适当和正确的文档注释（doc-comments）装饰你的代码，这些注释可以作为Sandcastle或其他文档引擎的“源代码”。花费大量时间和精力来记录所有代码，但我相信，正如你可能已经推断出的那样，这绝对是值得的。除了前面提到的其他人能够更轻松地使用您的代码之外，我发现记录我的代码还有一个重要的好处——它帮助我编写更好的代码。当我开始记录新方法或类时，我经常对自己说“哦，如果将此参数称为Y而不是X，则会更清晰。”或“糟糕——这个方法对于其他人来说不够通用；我需要添加一个Z参数。”或“哈！这个类没有完全正确地处理这些边角情况。”换句话说，描述您的类或方法或参数的行为会让您仔细考虑它，因此编写文档注释会导致更好的代码。

理论就讲到这里，如果你需要一些有关Sandcastle和SHFB的实用建议和指南，请查看我在Simple-Talk.com上的文章Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code。这篇文章详细记录了我通过对SHFB进行研究和实验所发现的所有内容。文章附带了一个方便的壁挂图表，其中包含了所有可以在文档注释中使用的已记录和未记录的元素和属性。以下是壁挂图表的一部分，以激发你的兴趣：

- Michael Sorens