问题标签 [xml-documentation]

使用 NDoc 或 Sandcastle 等工具，您可以从 .Net 代码 xml 文档生成文档。

所以我的问题是：如何轻松添加其他页面？

例如，我想在文档的顶层添加“词汇”或“关于”页面。

使用 SandCastle 之类的工具，我知道您可以使用“NamespaceDoc”类添加命名空间的文档，这很棒，但没有提供我想要的灵活性。

此外，如果这些页面可以通过 xml 文档链接（例如：“获取更多信息”），那就太好了，但由于我什至不知道插入页面的基本方法，所以这可能有点过分了。

我通常将类中的字段声明为私有字段以及从外部访问该字段的公共属性（到目前为止没有什么特别的微笑）：

现在我想知道是否有一种优雅而有效的方式来评论这种情况，而无需两次写相同的评论。换句话说，我想保留 IDE 在鼠标悬停时使用工具提示向我显示变量注释的功能。

到目前为止，我是这样评论的：

我想要这样的东西：

我知道使用 XML 标记来评论私有字段并不是很有意义，因为它们不会出现在生成的文档中，但我又只想拥有（IDE 内部的）评论工具提示。

也许有人有线索:)

我在一个程序集中有许多接口，我需要使用 XML-Doc 和 Sandcastle 记录这些接口。但是，在构建文档文件时，我还想忽略一些接口。现在我设法通过使用标记为 的接口编译程序集来做到这一点internal，但这更像是一种解决方法而不是问题的解决方案，因为事实上，那些需要是public. 是否有某种属性可以装饰不需要的属性，以便它们被忽略？

当方法的目的是计算一个值并返回它时，我发现自己记录它如下：

这里的returns标签没有提供任何新信息：它只是重复summary. （例外是返回的方法，bool很容易解释true和false返回值的含义。）

我错过了什么吗？是否有一种标准的 XML 文档块措辞方式来避免summaryandreturns标记之间的重复？

可能重复：
C#：如何在 xml 文档中引用泛型类和方法

我想为我的静态函数创建一个简短的文档（在 VS2010 中），它有一个IDictionary<TKey, TValue>参数。

例如 ：

我想在 VS2010 中创建一个文档，当你键入/3 次之后会自动生成如下：

我想这样写：字典key是某种东西，字典value是另外一种东西。

怎么做 ？

试图通过我的项目并扩展文档，并有以下情况：

cref 产生以下错误：

警告 C4638：应用于“Test.TypeOne.AAA”的 XML 文档注释：引用未知符号“Test::TypeTwo”。

有没有办法让 xml 文档识别 TypeTwo？我只是将 TypeTwo 放在 TypeOne 之上，但 TypeTwo 也作为 TypeOne 的 cref，所以我会回到同样的情况。

我只是愚蠢吗？

Noda Time有一个问题，即它发布的 XML 文档文件也包含所有内部和私有成员 - 这是一种耻辱。

幸运的是，Sandcastle Help File Builder有一个自定义的构建组件——IntelliSenseComponent理论上它确实做了正确的事情。不幸的是，我无法弄清楚如何正确配置它。

文档给出了这个例子：

并指出：

上面给出的示例取自 Sandcastle Help File Builder 的配置文件。与它一起使用时，替换标签 {@SHBFFolder} 和 {@OutputFolder} 用于在文件路径中插入帮助文件构建器的文件夹和项目的输出文件夹。这些在构建时被替换为适当的值。如果在您自己的构建脚本中使用该组件，请将标签分别替换为组件装配和输出文件夹的相对或绝对路径。

好吧，我正在使用 SHFB，所以我希望它能够工作。但是，除了绝对的工作路径之外，我什么也得不到。我试过了：

（我只是将 XYZZY 用作易于搜索的东西。）

查看源代码，我希望我可以使用环境变量，但这不起作用：

虽然这确实......

这有效：

...但我真的不想要一个绝对路径名。

文档表明所有这些都应该非常容易......我错过了什么？

涉及的版本：

• SHFB：1.9.3.0
• 沙堡：2.6.10621.1

我刚刚下载了这个应用程序的试用版，它似乎不起作用。我浏览了快速设置指南，一切看起来都很棒。现在，当我将光标放在任何类型的成员上并按 Ctrl+Shift+D 时，它什么也不做。我把它放在上面，里面等等......什么都没有。如果我在成员顶部按 Ctrl+Shift+A（两次），它会告诉我将其放置在“MyType myVariable; 形式的行中”。我不太确定这意味着什么，除非它指的是 C#，但这个项目是 VB.NET，它似乎无法识别。其他人有这个问题吗？我希望它能让事情变得更容易，因为我已经读过它可以记录整个文档，而不必逐个成员。

使用 VS 2010 高级版。

我试图在我的类 XML 文档中包含一个代码片段，但编译器抱怨 xml 元素未关闭！这是我想要实现的目标

我试图将代码片段替换为/// <c> MyClass class = new MyClass{String}(); </c>

有没有人经历过这种情况？

谢谢你的帮助

有一个有趣的。我正在使用 C# 中的 XML 文档注释记录一个方法。我想使用该指令来包含引用文件的所有内容。我正在记录一段代码，它接收格式化为 xml 文档的字符串，并且我想在参数文档中包含 XSD 文件。

这很好用，因为 Visual Studio 生成的 XML 符合我的预期。这是 XML 的一个片段：

但是，当我使用 Sandcastle 从中生成帮助文件时，没有显示 xsd 文件的内容，但 Sandcastle 没有报告任何错误。我尝试使用相对于帮助文件所在位置的文件名，即

但随后 Visual Studio 抱怨它找不到该文件。我把它们放在两个地方，仍然没有出现包含的文件。

有任何想法吗？