问题标签 [xml-documentation]

我正在使用 Sandcastle 2.4.10520 和 Sandcastle Help File Builder 1.8.0 来生成 .chm 帮助文件。

在我的文档中，我使用了<see>标签。

如果我尝试引用一个枚举，<see cref="NumberStyles"/>它就可以完美地工作。

如果我尝试引用一个枚举值，例如<see cref="NumberStyles.AllowTrailingWhite"/>在文档文件中获得一个链接，但该链接将我引导至未找到的 MSDN 页面

我没有收到任何警告 - 我的 xml 文档是正确的。

我注意到引用枚举值的 MSDN 页面也有一个 Page not found 链接。例如：UInt64.Parse Method (String, NumberStyles, IFormatProvider)引用NumberStyles.AllowHexSpecifier，这会导致另一个MSDN Page not found。

我应该引用枚举而不是枚举值吗？

我应该怎么做才能引用枚举？甚至可能吗？

有没有办法直接从 Visual Studio 的代码文档中生成可读的文档文件？（也考虑到 2010 年）

代码示例：

我：我是 .NET 平台的新手。

问题

在 Java 中，您可以通过创建 package-info.java 或 package.html 文件并将其存储在包文件夹中来将包级文档添加到项目中。如何使用 Visual Studio 2010 在 C# 中向我的项目添加等效文档？

背景

我喜欢在我正在处理的源代码项目的包/文件夹级别上下文中编写描述我的动机的文档。我已经非常习惯使用各种语言（特别是 Java）的这种工作流程，并且我相信这是记录我的项目的好方法。

我想要一些工具，最好是插入 VS 2008/2010 的工具，它将通过我的方法并添加关于它们可能抛出的异常的 XML 注释。我不希望为我生成 XML 标记或其他 XML 标记，因为我会自己填写这些标记，但如果即使在/方法上我也能看到可能引发哪些异常<summary>，那就太好了。否则，我会发现自己正在浏览这些方法并将鼠标悬停在其中的所有方法调用上以查看异常列表，然后更新该方法的列表以包含这些异常。也许VS宏可以做到这一点？privateprotected<exception

由此：

对此：

更新： 似乎该工具必须递归地遍历这些方法，例如， method1 调用 method2 调用 method3 记录为 throwing NullReferenceException，因此该工具将 method2 和 method1 记录为也 throwing NullReferenceException。该工具还需要消除重复项，例如，如果方法中的两个调用被记录为 throwing DirectoryNotFoundException，则该方法只会列出<exception cref="System.IO.DirectoryNotFoundException"/>一次。

当我键入一些类时，例如控制台，然后按 ctrl+空格和智能感知显示提示“类 System.Console 表示标准输入、输出和错误流......”如何以编程方式获取此文本。在谷歌上找不到，可能我是愚蠢的菜鸟。谢谢。

允许 VB.NET 代码嵌入可以由该工具提取的文档注释（对应于 C# 文档注释）的工具的名称是什么？

我正在浏览一些旧代码；Visual Studio 2005 时代。一个简单的例子是：

有一个集成到 Visual Studio 菜单中的第 3 方免费（开源？）文档生成器工具。

我在这里看到了涉及Microsoft's XML documentation tags 的各种问题，但我在添加一些示例代码时遇到了麻烦：

这给了我：

<如果您直接阅读源代码而不是 DOxygen 输出（例如），那么除了使用使示例更难遵循之外，还有什么方法可以解决这个问题？..或者<代码是这里唯一的选择吗？

[编辑]我已经尝试过建议的 CDATA 块，但它似乎只适用于单行：

..但不是多行注释，这实际上可能是一个可读的例子：

[Edit2]尝试了 pierrre 的建议，即从可以预见的失败的最后两个语句前面删除 \\'s：

给出：

如果有一个接口和一个实现它的类，并且您希望在其上添加 xml 注释以在 VS intellisense 或文档中使用，您会将 xml 注释放在哪里？在接口的方法上还是在具体的类方法上？正确的方法是什么？

我的想法是将它放在接口中，因为我们正在使用接口声明变量。而且我认为如果我也对具体类发表评论并看到这可能会导致同一方法的不同文档是多余的。

有什么想法、建议吗？

我需要什么工具来生成如下所示的 XML intellisense 帮助文件？

假设在 Visual Studio 中我有一个新项目，其中包含来自旧项目的一些相同 API，并且我想将 xml 文档复制到新项目中。有没有一种方法可以在不手动复制粘贴的情况下做到这一点？