.NET xml 文档 - 继承文档

Question

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

Answer 1

我有更好的答案: FiXml .

使用 GhostDoc 克隆评论当然是可行的方法，但它有很大的缺点，例如:

当原始注释发生更改时(在开发过程中经常发生)，
它的克隆不是。

你正在产生大量的重复。如果您使用任何
源代码分析工具(例如 Team City 中的 Duplicate Finder)，它将
主要查找您的意见。

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

不支持从基类或接口(interface)继承文档。 IE。任何被覆盖的成员的文档都应该从头开始编写，尽管通常至少继承它的一部分是非常可取的。

不支持插入常用文档模板 ，例如“这种类型是单例的 - 使用它的 <see cref="Instance" />属性来获取它的唯一实例。”，甚至“初始化 <CurrentType> 的新实例类(class)。”

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

<inheritdoc />, <inherited />标签

<see cref="..." copy="..." /> <see/> 中的属性标签。

这里是 its web page和 download page (断开的链接)。

最后还有 <inheritdoc>标记 Sandcastle - 使用它肯定比复制 XML 注释更好，但与 FiXml 相比，它几乎没有缺点:

SandcaSTLe 生成已编译的 HTML 帮助文件 - 它不会修改 .xml文件
包含提取的 XML 注释。但是这些文件被许多工具使用，
包括 .NET Reflector 和类浏览器\Visual Studio .NET 中的 IntelliSense。
因此，如果您只使用 SandcaSTLe，您将看不到继承的文档。

SandcaSTLe 的实现没有那么强大。例如。没有<see ... copy="true" /> .

见 Sandcastle's <inheritdoc> description了解更多详情。