问题标签 [xml-documentation]

我一直很重视使用 C# xml 语法为类和方法编写漂亮的代码注释。我一直希望以后能够轻松地导出它们。

今天我实际上必须这样做，但我很难找出方法。有什么我想念的吗？我想去Menu->Build->Build Code Documentation，但是那里没有选择。

如何在 .Net 中记录内联成员？让我解释。大多数从注释中提取文档的工具都支持某种内联文档，您可以在其中在成员声明之后添加简要说明。就像是：

有没有办法在 C# 或 .NET 语言中做到这一点？

我在 MSDN 链接中看到，例如“CompareOrdinal Overloads”。如何在 C# 中编写这样的链接？

我试过：

但是编译器给了我一个警告，说它是具有其他重载的方法的模棱两可的引用。

（初学者问题：我真的需要编写这个标签来链接到重载，还是它是由文档处理器自动生成的？）

我正在尝试对类的成员使用 XML 文档，并且在某些情况下，我想使用标记来引用泛型类型。这里的问题是当指定多个泛型类型参数时会产生警告。很容易找到如何使用单个参数引用泛型类型，如下所示：

但是，尝试这样的事情会产生警告：

似乎我对具有多个类型参数的引用使用了错误的语法，或者 C# 的 XML 文档当前不支持此类引用。奇怪的是，我似乎在 MSDN 或 Sandcastle 文档（我正在使用它来编译文档，并且还抱怨语法）中找不到任何关于此的信息。任何澄清在这里将不胜感激。

在编写 xml 文档时，您可以使用<see cref="something">something</see>，当然可以。但是如何引用具有泛型类型的类或方法呢？

如果我要在某处编写 xml 文档，我将如何引用花哨的类？我怎样才能引用一个FancyClass<string>？方法呢？

例如，在另一个类中，我想让用户知道我将返回一个FancyClass<int>. 我怎么能为此做一个see cref的事情？

这个问题源于这个问题 Code documentation how much is too much?

答案之一是将您的 xml 文档保存在单独的文件中。我真的很喜欢这个答案，因为当我查看代码时，文档的冗长令人讨厌，另一方面，在通过智​​能感知搜索正确的方法或发布文档时，冗长很有用。

答案是使用包含标签

这里还有一篇关于包含标签的 MSDN 文章。

我想出了如何保留摘要信息，但我不知道也找不到如何将方法文档放在那里。（这比课程摘要本身更重要。

我正在使用 xml 注释来记录我的组件的公共以及内部和私有成员。我想将生成的文档 xml 文件与组件程序集打包在一起，以便在最终产品中启用“丰富”（例如，带有方法、异常和参数描述）Visual Studio Intellisense。问题在于 C# 编译器为所有内容（包括内部类、方法、内部枚举的私有字段等）创建文档条目，并且似乎没有切换到“仅公共成员”模式。

现在我不想检查超过 50 个文件，每个文件都有 XX 方法，并删除私人和内部成员的所有评论。即使我这样做了，我也可能不会在自动生成的资源文件上取得太大的成功，因为这些强类型资源类是自动注释的并且是非公开的。

我的问题是：是否有一些我忽略的选项/标志？如果不是，是否有一些工具可以帮助将公共成员与其他成员区分开来（在我开始编写代码之前）？

伙计们，

我正在创建一个新的 WCF 服务并从我的服务接口开始。看起来像：

现在，我还在另一个文件中创建了一些数据协定，描述了 SomethingRequest 和 SomethingResponse 消息。

我编译了我的项目并启动了 svcutil.exe 以从 DLL 中提取元数据（WSDL 和 XSD） - 但我似乎无法弄清楚是否有办法将我的所有评论和解释放入 WSDL/XSD 到 /节点。

我是否对另一个不起眼的 svcutil.exe 参数视​​而不见，还是真的没有办法在元数据中自动生成此文档？

编辑：好的，根据 Marc Gravell 的回答，注释和文档字符串既不在编译的 DLL 中，也不在 MEX 元数据交换协议上可用（可惜！）。

SO THEN：如果您需要向第三方提供访问您的服务所需的信息，您如何记录您的 WCF 服务？是否有“NService”或“WCF 沙堡”工具可以扫描我的 WCF 服务库并从源代码构建 WSDL 和 XSD，包括注释？

似乎找不到很多工具和方法来做到这一点 - 老实说，令我惊讶的是......

马克

1. 使用带有 XML 文档文件的外部程序集时，如何让 Visual Studio 找到它？

2. 当有一个 XML 文档文件时，是否有一个程序或 xml 转换文件或我可以用来以一种很好的方式查看它的东西？不一定像 msdn 文档查看器那样复杂，但至少比纯 xml 更好...

为谓词助手类编写一些 XML 文档。但我不知道我可以在Expression<Func<T, bool>>没有语法错误的情况下引用 an 。甚至可能吗？我试过这个：

但是我得到了一条红色的波浪线{T, bool}}。这虽然有效：

有人有线索吗？

更新：

给出的答案（我接受了）似乎确实有效。但现在我开始收到很多关于无法解决问题的警告。我有一个名为的类ExpressionBuilder<T>，它适用于Expression<Func<T, bool>>很多。所以我当然想在我的 XML 注释中引用它。

我已经尝试了我知道的两个版本：

但两者都不起作用。（在最后一个上，ReSharper 在{T,Boolean}}我使用过的所有地方都在编译时收到了两个警告，上面写着：

1. 'blah blah' 上的 XML 注释具有无法解析的 cref 属性 'Expression>'
2. 类型参数声明必须是标识符而不是类型。另请参阅错误 CS0081。

在我试图引用的某个地方遇到同样的问题Range<Nullable<DateTime>>（Range<DateTime?>也没有工作。使用 { } 和 with < >）

我不应该参考这些泛型吗？