.NET xml 文档 - 继承文档

Question

NDoc 有一个 XML 元素 继承文档 它允许您从父类（或实现的接口）继承成员的文档。但是，Visual Studio（即C# 编译器）不理解此标签，并抱怨文档不存在或不完整。StyleCop 和其他一些工具也是如此。有替代方法吗？如何在不重复 XML 描述的情况下保持文档完整？

Answer 1

另一种方法是使用 GhostDoc - 一个自动生成的Visual Studio加载项给你的评论。这当然会复制XML描述，这是您要避免的一部分 - 但至少它会自动为您完成。

如果您完全不使用继承的方法或覆盖接口方法，那么会发生什么？我怀疑它取决于你如何配置NDoc，但肯定在MSDN文档中似乎只是自然地继承了文档 - 并且快速检查建议当你不生产时VS不会发出呜呜声继承方法的文档。当然值得一试。

Answer 2

我有一个更好的答案： 固定值.

使用 GhostDoc 克隆注释当然是可行的方法，但它有明显的缺点，例如：

• 当最初的评论更改（在开发过程中经常发生）时，其克隆就不会。
• 您正在生成大量重复项。如果您使用任何源代码分析工具（例如在Team City中重复的Finder），它将主要找到您的评论。

FiXml 的简短描述：它是由 C# \ Visual Basic .Net 生成的 XML 文档的后处理器。它作为 MSBuild 任务实现，因此很容易将其集成到任何项目中。它解决了一些与用这些语言编写 XML 文档相关的烦人的情况：

• 不支持从基类或接口继承文档。 IE。任何被重写成员的文档都应该从头开始编写，尽管通常情况下至少继承其中的一部分是非常可取的。
• 不支持插入常用文档模板, ，例如“此类型是单例 - 使用其 <see cref="Instance" /> 属性来获取它的唯一实例。”，甚至“初始化一个新实例 <CurrentType> 班级。”

为了解决上述问题，提供了以下附加 XML 标签：

• <inheritdoc />, <inherited /> 标签
• <see cref="..." copy="..." /> 属性在 <see/> 标签。

这是 它的网页 和 下载页面 （断开的链接）。

最后，还有 <inheritdoc> 标记在 沙堡 - 使用它肯定比复制 XML 注释更好，但与 FiXml 相比它有一些缺点：

• Sandcastle 生成已编译的 HTML 帮助文件 - 它不会修改 .xml 包含提取的XML注释的文件。但是这些文件是由许多工具使用的，包括.NET反射器和类浏览器 Intellisense在Visual Studio .NET中。因此，如果您只使用 Sandcastle，您将不会在那里看到继承的文档。
• Sandcastle 的实现功能不太强大。例如。是没有<see ... copy="true" />.

看 沙子城堡 <inheritdoc> 描述 了解更多详情。

Answer 3

我构建了一个命令行工具来对XML文档文件进行后处理，以添加对<！> lt; inheritdoc / <！> gt;的支持。标签

它对源代码中的Intellisense没有帮助，但它确实允许修改后的XML文档文件包含在NuGet包中，因此可以在引用的NuGet包中使用Intellisense。

有关详细信息，请参见 www.inheritdoc.io 。（