.NET中的XML代码注释

Question

您在代码文件中使用了多少XML注释，以及如何使用它们？我已经看到你可以使用它们来生成XML文档，但是这个XML文档可以用来为你的代码生成一个HTML帮助文件或模式文件吗？

此外，您是否使用过任何自动生成的评论工具（即GhostDoc），以及您的印象如何？

想法？

Answer 1

XML本身的文件可能是有用的。这样，API的任何使用者都可以从IDE中获得有用的信息（通过Intellisense或对象浏览器）。

现在也许最大程度地使用XML注释是从这些构建的XML文件生成帮助文档。 Microsoft Sandcastle是目前关于此的方法。它可以生成HTML帮助1（即CHM）文件或HTML帮助2（即可以集成到Visual Studio帮助中的帮助文件）。 （注意：过去，NDoc的选项似乎更具吸引力 - 有些人仍在使用它 - 但Sandcastle似乎是目前官方推荐的方法，尤其是考虑到它相当稳定和完整，几乎可以满足任何需求）请参阅SandcastleDocs网站开始（我相信这是由微软的一位开发人员非正式组合的）。特别是，你会想看看Sandcastle Help File Builder的GUI - 以我的经验，我发现它是一个很好的工具。

Answer 2

是的！我使用它们，并且这是所有项目的一项要求，我们将其纳入其中。至于细节的级别，它取决于代码的目的。至少所有参数和公共方法都会有摘要信息。复杂的项目通常具有代码示例，并且记录所有特别抛出的异常。

现在我正在使用SandCastle来完成文档构建，并且您可以在没有任何问题的情况下转到HTML或CHM！我还使用了SlickEdit，它可以快速解析，并且它也很棒！

Answer 3

是的，我确实使用这个功能，并认为这是所有开发者评论他们的api的好习惯。一旦你为几个apis完成了这个任务，并且只要你保持最佳状态，那么维护它并不难。

选项1：SandCastle 我试过使用这个，但是我发现有太多的安装程序需要运行，安装和学习配置。最后，我最终得到了一个chm文件，但是我真的想要更轻一点的东西。

好处是最终产品看起来非常专业。尽管如此，它并不适合我的情况。

选项2：NDoc 我上次检查时，这个项目没有被维护，只能用于.NET的1.1版本。

方案3：XSLT 有人在CodeProject上写了XSLT文件中查找该

http://www.codeproject.com/KB/XML/XMLDocStylesheet.aspx

我试了一下，在这里是如何工作的。 构建您的项目并将xslt文件放入与输出的xml文件相同的目录中。双击XML文件时，将显示一个格式化的网页，而不是xml文档。

对我来说，这是最好的选择。

Answer 4

至少我包含公共API的注释并生成xml文件。这足以让智能感知工作，并且它也出现在Reflector中。

就个人而言，我不打扰sandcastle等 - 但我可能为ISV项目。

Answer 5

我们用XML注释记录所有方法和属性。两者都用于内部文档目的，并且能够为我们的二进制文件提供帮助文件。在intellisense中弹出一个方法的文档是非常好的。

我们使用的是GhostDoc - 它可以提供 - 通常是OK - 默认文档，但请记住，GhostDoc只能记录从方法和参数名称中推断出的内容。因此，我们的规则是您可以使用GhostDoc来启动文档;然后适当地编辑它 - 在许多情况下，参数的默认文档将会很好。在简单的情况下，我们也只是坚持使用默认文档，如果它是有道理的。

帮助文件可以使用Sandcastle(download)生成。另外，the Sandcastle Help File Builder是一个GUI，可以让您更轻松地开始使用Sandcastle。

Answer 6

我试着去做任何不明显的方法。我喜欢它包含Intellisense中的文档。

Answer 7

我以前使用过微软的SandCastle工具来从Xml注释中生成MSDN样式文档，并且真的很幸运。假设它是用于生成所有.net框架文档的工具，这些文档也恰好来自Xml注释。如果从构建伴随着DLL文件分发XML文件

http://msdn.microsoft.com/en-us/vstudio/bb608422.aspx

Answer 8

我正在利用NuDoc以降价格式生成静态API网站。 API是干净的，现代的，非常轻巧，易于使用（如果我可以这么说）; http://kzu.to/nudoc

它也是开源的，所以修正和改进总是受欢迎的。