【发布时间】：2008-11-22 13:53:14
【问题描述】：
NDoc 有一个 XML 元素 inheritdoc，它允许您从父类（或实现的接口）继承成员的文档。但是，Visual Studio（即 C# 编译器）不理解此标记并抱怨文档不存在或不完整。 StyleCop 和其他一些工具也是如此。有替代方法吗？您如何在不重复 XML 描述的情况下保持文档完整？
【问题讨论】：
标签： .net documentation ndoc
【发布时间】：2008-11-22 13:53:14
【问题描述】：
我有一个更好的答案：FiXml。
使用 GhostDoc 克隆 cmets 确实是可行的方法，但它有明显的缺点，例如：
- 当原始注释被更改时（在开发过程中经常发生）， 它的克隆不是。
- 您正在产生大量重复。如果您使用任何 源代码分析工具（例如 Team City 中的 Duplicate Finder），它将 主要是找到你的 cmets。
FiXml 的简短描述：它是由 C#\Visual Basic .Net 生成的 XML 文档的后处理器。它是作为 MSBuild 任务实现的，因此很容易将其集成到任何项目中。它解决了一些与用这些语言编写 XML 文档相关的烦人案例：
- 不支持从基类或接口继承文档。即任何被覆盖的成员的文档都应该从头开始编写，尽管通常至少继承它的一部分是非常可取的。
-
不支持插入常用的文档模板，比如“这个类型是单例的——使用它的
<see cref="Instance" />属性来获取它的唯一实例”，甚至是“初始化一个@的新实例” 987654327@上课。”
为解决上述问题，提供了以下附加 XML 标记：
-
<inheritdoc />, <inherited />标签 -
<see/>标签中的<see cref="..." copy="..." />属性。
这里是its web page 和download page（链接断开）。
最后，Sandcastle中有<inheritdoc>标签——使用它肯定比复制XML cmets要好，但与FiXml相比它几乎没有缺点：
- Sandcastle 生成已编译的 HTML 帮助文件 - 它不会修改
.xml文件 包含提取的 XML cmets。但是这些文件被许多工具使用， 包括 .NET Reflector 和类浏览器\Visual Studio .NET 中的 IntelliSense。 因此，如果您只使用 Sandcastle，您将看不到继承的文档。 - Sandcastle 的实现没有那么强大。例如。没有
<see ... copy="true" />。
【讨论】：
-
理论上不错（链接为 +1），但在实践中，我发现 FiXml 错误太多，不实用。它偶尔会锁定文件，我必须重新启动 VS 才能再次构建。我注意到它将所有引用程序集加载到当前的
AppDomain中，而不是创建一个单独的AppDomain以便以后卸载。这可能就是原因。 -
FiXml 现在正式不受支持，并且原样在 VS2013 中不起作用，尤其是在 x64 下。稍微玩一下构建脚本会使其运行，但实际上无法正常工作，并且无法运行两次。有关更多信息，请参阅 Xtensive 的 SO-lookalike 帮助网站上的此问题：support.x-tensive.com/question/5419/problem-with-fixml
另一种方法是使用GhostDoc - Visual Studio 的一个插件，它会自动为您生成 cmets。这当然会重复 XML 描述，这是您要避免的部分内容 - 但至少它会自动为您完成。
如果您只为被继承的方法或覆盖接口方法而完全放弃文档会发生什么？我怀疑这取决于您如何配置 NDoc，但肯定在 MSDN 文档中似乎只是自然地继承了文档 - 并且快速检查 suggests 当您不提供时 VS 不会抱怨继承方法的文档。当然值得一试。
【讨论】：
-
感谢您的回复。如果省略 cmets，NDoc 会正确继承文档，但 VS 仍然会抱怨缺少 doc cmets，这有点烦人。 GhostDoc 是一个不错的工具。 ReSharper 还有一个相关功能 - 从 base 复制 cmets。
我构建了一个命令行工具来对 XML 文档文件进行后处理，以添加对
它对源代码中的 Intellisense 没有帮助，但它允许将修改后的 XML 文档文件包含在 NuGet 包中，因此可以在引用的 NuGet 包中与 Intellisense 一起使用。
详情请参阅www.inheritdoc.io（提供免费版本）。
【讨论】：