问题标签 [xml-documentation]

我今天启动了 Sandcastle Help File Builder 来为我的解决方案生成文档，其中包含大约十几个项目。因为我只想为发布版本（不包括我的所有测试项目）生成文档并在之后运行 Sandcastle，所以我在窗口顶部选择了“发布”，就像在 VS 中一样。Sandcastle 会在我的 \bin\release 子文件夹中为每个项目适当地查找生成的 XML 文件。但是，当它找不到我的测试项目的 DLL 时，它会出错。它显然在解决方案文件中看到了这些项目，但没有意识到我在 Release 中没有为它们构建。我尝试在“API Filter”属性中取消选择它们，但这并没有改变任何东西。

我怎样才能让 Sandcastle 忽略这些项目？

我使用 ILMerge 将我的几个 C# 项目 DLL 合并到一个用于整个解决方案的 DLL 中。我让每个项目为 Intellisense 生成其文档的 .XML 文件，当我尝试在另一个解决方案中使用合并的 DLL 作为参考时，我无法显示这些注释。我将这些文件都放在同一个目录中：

• MergedProjectDlls.dll
• 项目1.XML
• 项目2.XML
• 项目3.XML
• 项目4.XML

我尝试将单个项目 XML 文件重命名为 MergedProjectDlls.XML，然后在 Visual Studio 中删除并重新添加引用，但 Intellisense 仍然没有收到我知道的我重命名的项目 XML 文件中存在的注释。

我希望以某种方式将所有这些项目 XML 文件合并到一个名为 MergedProjectDlls.XML 的文件中。那可能吗？当它与 MergedProjectDlls.dll 位于同一目录中时，Intellisense 会自动获取它吗？

编辑：刚刚在MSDN上找到了这个：

要将生成的 .xml 文件用于 IntelliSense 功能，请让 .xml 文件的文件名与您要支持的程序集相同，然后确保 .xml 文件与程序集位于同一目录中。因此，在 Visual Studio 项目中引用程序集时，也会找到 .xml 文件。

并且：

除非您使用 /target:module 进行编译，否则文件将包含指定文件名称的标记，该文件包含编译输出文件的程序集清单。”

我正在使用xsd.exe从 xsd 文件集合生成 C# 类。xsd 文件使用<xsd:documentation>标签来包含有用的描述。例子：

不幸的是，所有这些都在生成的 C# 类中丢失了。有趣的是，每个类都附有 一个空的备注文档标签。

如何将此文档包含在生成的 C# 类中（在或文档标签中）？

是否有软件/应用程序可以将我们所有的 VS2008 XML 文档注释文件存储在一个地方，并且可以充当所有这些文档的库？

我们正在创建许多相互关联的 Web 项目，我们需要将 VS 创建的所有 XML 文档放在一个地方。因此，它可以充当我们可以通过单个软件/应用程序访问所有文档和搜索代码或参考的地方。

当然它是 XML，我们可以创建 XSLT 并转换所有文档，但我们首先要寻找已经完成的东西。自定义应用程序是我们的第二选择。

感谢您的建议！

在我对方法和类的 .NET XML 注释中，我尝试以<example><code></code></example>块的形式提供使用示例。当我使用 Sandcastle 使用我的 XML 文档生成 .chm 文档文件时，它的格式总是很好并且尊重我的<code>块中的换行符。但是，当我在 Visual Studio 的对象浏览器中浏览类和方法时，所有内容都在一行中运行，并且字体完全相同（代码没有等宽）。这是由于我在 XML 注释中没有做的事情，还是对象浏览器只是愚蠢的？我专门使用 Visual Studio 2008 Team System。

我们有一个 C++/CLI 混合模式程序集，从中我们生成了一个 XML 文件，用于 Sandcastle 文档和 Intellisense。

我们使用一个工具来扫描程序集并为我们创建所有条目，不幸的是我不知道这个工具是如何工作的，它无法处理方法签名，例如：

XML 文件中的这个参数应该是 System.Int32!CompilerServices.IsLong@ 但我们的工具无法处理。

换句话说，如何扫描程序集以创建 Intellisense 所需的 XML 文件？

在使用 C# 中的 Web 客户端软件工厂 (WCSF) 开发 ASP.net Web 应用程序时，我遇到了这个困境，同样的情况也适用于其他平台和语言。我的情况是这样的：

我根据WCSF范式为每个网页/用户控件定义一个I View接口，然后让页面类实现I View接口，基本上实现接口中定义的每个方法。当我尝试在方法级别添加 xml-documentation 时，我发现自己基本上为接口方法及其在实现类中的对应部分重复了相同的注释内容。

所以我的问题是：接口方法和相应的类方法的文档内容之间是否应该存在一些实质性差异？他们应该强调不同的方面还是什么？

有人告诉我，接口方法注释应该说方法应该做什么，而类方法注释应该说它是如何做到的。但我记得之前在某处读过，方法级别的注释应该只说方法应该做什么，而不是方法的实现细节，因为实现不应该是方法用户关心的问题，它可能会改变。

我在某些方法中添加了<returns>xml 标记，但在 IntelliSense 中看不到它的内容。

这是我的代码：

有没有办法显示这个内容？

我最近一直在写很多 VC++ 2008 / CLI 软件，并且正在使用 C#/CLI 风格的文档：

我发现自己非常频繁地重新输入这些块，坦率地说，它变得重复了。当您创建新函数定义或更新现有定义时，有什么方法可以让 Visual Studio 自动创建/更新这些块？

我想记录枚举类型字段的默认值：

编译器警告它无法解析引用。前缀 F: 或 M: 会使编译器静音，但 E: 也可以，所以我不确定哪个前缀是正确的。