.NET xml docs - 继承文档

Question

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

Answer 1

我有更好的答案： FiXml 。

使用GhostDoc克隆注释肯定是有效的方法，但它有明显的缺点，例如：

• 当原始评论发生变化时（在开发过程中经常发生）， 它的克隆不是。
• 你正在制作大量的副本。如果您正在使用任何 源代码分析工具（例如Team City中的Duplicate Finder），它会 主要找你的意见。

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

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

要解决上述问题，请提供以下附加XML标记：

• <inheritdoc />, <inherited />标签
{li> <see cref="..." copy="..." /> <see/>标记中的属性。

以下是its web page和download page（已损坏的链接）。

最后，Sandcastle 中有<inheritdoc>标记 - 使用它比复制XML注释更好，但与FiXml相比，它有一些缺点：< / p>

• Sandcastle生成已编译的HTML帮助文件 - 它不会修改.xml个文件 包含提取的XML注释。但是这些文件被许多工具使用， 包括.NET Reflector和Visual Studio .NET中的类browser \ IntelliSense。 因此，如果您只使用Sandcastle，那么您将看不到继承的文档。
• Sandcastle的实施不那么强大。例如。不是 <see ... copy="true" />。

有关详细信息，请参阅Sandcastle's <inheritdoc> description。

Answer 2

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

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

Answer 3

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

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

有关详细信息，请参阅www.inheritdoc.io（可用免费版本）。