.NET xml文档-继承文档

Question

NDoc有一个，它允许您从父类(或实现的接口)继承成员的文档。但是，Visual (即C#编译器)不理解此标记，并抱怨文档不存在或不完整。StyleCop和其他一些工具也是如此。有没有其他办法？如何保持文档完整，同时又不重复XML描述？

Answer 1

另一种选择是使用GhostDoc - Visual的外接程序，它会自动为您生成注释。当然，这重复了XML描述，这是您试图避免的部分内容--但至少它会自动为您完成。

如果您只是为了继承的方法或重写接口方法而完全关闭文档，会发生什么情况？我怀疑这取决于您是如何配置NDoc的，但是在MSDN文档中，似乎很自然地继承了这些文档--快速检查表明，当您不对继承的方法进行处理时，VS不会发牢骚。值得一试，当然。

Answer 2

我有一个更好的答案：FiXml__。

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

• 当原始注释被更改时(开发过程中经常发生这种情况)，它的克隆就不会发生。
• 你在生产大量的复制件。如果您正在使用任何源代码分析工具(例如Team中的重复查找器)，它将主要找到您的评论。

FiXml的简短描述:它是C# \ Visual .Net生成的XML文档的后处理程序。它是作为MSBuild任务实现的，所以很容易将它集成到任何项目中。它解决了几个与用这些语言编写XML文档有关的恼人的案例：

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

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

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

这是其网页和下载页面 (坏链接)。

最后，<inheritdoc>标记存在于https://github.com/EWSoftware/SHFB中--使用它肯定比复制https://github.com/EWSoftware/SHFB注释好，但与FiXml相比，它几乎没有什么缺点：

• 沙堡生成编译后的help文件--它不修改包含提取的.xml注释的文件。但是这些文件被许多工具所使用，包括.NET反射器和Visual .NET中的类browser \ IntelliSense。
• 沙堡的实现不那么强大。这不是<see ... copy="true" />。

有关更多细节，请参见描述。

Answer 3

我构建了一个命令行工具，用于对XML文档文件进行后处理，以添加对标记的支持。

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

有关详细信息，请参阅www.inheritdoc.io (可获得免费版本)。