NDoc有一个XML元素inheritdoc，允许您继承父类（或实现的接口）的成员文档。然而，Visual Studio（即C#编译器）不理解此标记，并抱怨文档不完整或不存在。因此，StyleCop和一些其他工具也是如此。是否有替代方法？如何保持文档完整，但又不重复XML描述？
3个回答
23
我有一个更好的答案：FiXml。
使用GhostDoc克隆注释确实是一种可行的方法，但它有很大的缺点，例如：
- 当原始注释发生更改（在开发过程中经常发生），它的克隆不会更新。
- 你会产生大量的重复。如果你使用任何源代码分析工具（例如Team City中的重复项查找器），它将主要找到你的注释。
FiXml的简短描述：它是由C# / Visual Basic .Net生成的XML文档的后处理器。它被实现为MSBuild任务，因此很容易集成到任何项目中。它解决了这些语言中写XML文档时的一些令人讨厌的问题：
- 不支持从基类或接口继承文档。也就是说，任何重写成员的文档都应该从头开始编写，尽管通常至少继承部分文档是非常可取的。
- 不支持插入常用文档模板，例如“此类型是单例 - 使用其
<see cref="Instance" />属性获取唯一实例。”，或者甚至是“初始化<CurrentType>类的新实例。”
为了解决上述问题，提供了以下附加的XML标记：
<inheritdoc />, <inherited />标签<see cref="..." copy="..." />属性在<see/>标记中。
最后，在Sandcastle中有一个<inheritdoc>标签，使用它肯定比复制XML注释更好，但与FiXml相比，它有一些缺点：
- Sandcastle生成已编译的HTML帮助文件 - 它不会修改包含提取的XML注释的
.xml文件。 但是这些文件被许多工具使用，包括.NET Reflector和Visual Studio .NET中的类浏览器IntelliSense。因此，如果仅使用Sandcastle，则在那里看不到继承的文档。 - Sandcastle的实现功能较弱。例如，没有
<see ... copy="true" />。
有关详细信息，请参见Sandcastle的<inheritdoc>说明。
- Alex Yakunin
2
2理论上看起来不错（链接加一分），但实际使用中我发现FiXml太容易出现错误，不太实用。有时它会在文件上留下锁定，我必须重新启动VS才能再次构建。我注意到它将所有引用程序集加载到当前的“AppDomain”中，而不是创建一个可以稍后卸载的单独的“AppDomain”。这可能就是原因。 - Kent Boogaart
4FiXml现已正式停止支持，原版本无法在VS2013下工作，特别是在x64环境下更是如此。稍微尝试一下构建脚本可能会使其运行，但实际上它不能正常工作，且无法运行两次。在Xtensive的类似于SO的帮助网站上查看有关此问题的更多信息：http://support.x-tensive.com/question/5419/problem-with-fixml - Eric Dand
14
一种选择是使用GhostDoc——Visual Studio 的插件，可以自动为您生成注释。当然，这会重复XML描述，这也是您要避免的部分——但至少它会自动完成。
如果对于正在被继承或覆盖接口方法的方法完全省略文档会发生什么？我猜这取决于您如何配置NDoc，但在MSDN文档中似乎只是自然地继承了文档，并且快速检查表明 VS不会因您未为继承的方法提供文档而抱怨。值得一试。
- Jon Skeet
1
谢谢您的回复。如果省略注释，NDoc 将正确继承文档，但是 VS 仍然会抱怨缺少注释，这有点烦人。 GhostDoc 是一个不错的工具。ReSharper 也有一个相关功能-从基类复制注释。 - petr k.
2
我建立了一个命令行工具来后处理XML文档文件，以添加对<inheritdoc/>标签的支持。
它不能帮助源代码中的Intellisense，但它允许修改后的XML文档文件被包含在NuGet包中，并因此与引用的NuGet包中的Intellisense一起使用。
有关详细信息，请参见www.inheritdoc.io（提供免费版本）。
它不能帮助源代码中的Intellisense，但它允许修改后的XML文档文件被包含在NuGet包中，并因此与引用的NuGet包中的Intellisense一起使用。
有关详细信息，请参见www.inheritdoc.io（提供免费版本）。
- K Johnson
网页内容由stack overflow 提供, 点击上面的可以查看英文原文，
原文链接
原文链接