.NET中的XML代码注释 [英] XML Code Comments in .NET

问题描述

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

How much do you use the XML comments in your code files, and how do you use them? I've seen that you can use them to generate XML documentation, but can this XML documentation be used to generate an HTML help file or schema file for your code?

，你使用任何自动生成评论工具（即GhostDoc），你的印象是什么？

Also, have you used any auto-generating comment tools (i.e. GhostDoc), and what are your impressions?

XML文档本身可以是有用的，如果你能够使用XML文档，那么你可以使用XML文档来解决这个问题。

Thoughts?

推荐答案

您从构建一起分发XML文件以及DLL。这样，API的任何用户都可以从IDE中获得有用的信息（通过Intellisense或对象浏览器）。

XML documentation by itself can be useful if you distribute the XML files from the build along with the DLLs. This way, any consumers of the API have useful information available from within the IDE (via Intellisense or the object browser).

现在或许最大的使用XML注释是从这些构建的XML文件生成帮助文档。 Microsoft Sandcastle 是目前处理此问题的方法。它可以生成HTML帮助1（即CHM）文件或HTML帮助2（即可以集成到Visual Studio帮助中的帮助文件）。 （注意：在过去，NDoc的选项可能看起来更有吸引力 - 有些人仍然使用它 - 但Sandcastle似乎是这个时候的官方和推荐的方法，特别是因为它是相当稳定和完全足够几乎任何目的。）请参阅 SandcastleDocs 网站开始使用（这是由Microsoft的开发人员之一非正式组合在一起的我相信）。特别是，您需要查看 Sandcastle帮助文件生成器 GUI - 根据我的经验，我发现它是一个很好的工具。

Now perhaps the greatest use of XML comments is the generation of help documentation from these built XML files. Microsoft Sandcastle is the way to go regarding this at the moment. It can produce HTML Help 1 (i.e. CHM) files or HTML Help 2 (i.e. help files that can integrate into Visual Studio Help). (Note: In the past, the option of NDoc may have seemed more appealing - and some people still use it - but Sandcastle seems to be the official and recommended method at this moment, especially given that it's reasonably stable and complete enough for almost any purpose.) See the SandcastleDocs website to get started (this was unofficially put together by one of the developers at Microsoft I believe). In particular, you'll want to check out the Sandcastle Help File Builder GUI - in my experience I've found it to be an excellent tool.

这篇关于.NET中的XML代码注释的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！