.NET xml文档-继承文档

我有一个更好的答案: FiXml .

使用GhostDoc克隆注释当然是一种可行的方法,但它有明显的缺点,例如:

• 当原始注释发生变化时(在开发过程中经常发生), 它的克隆不是。
• 你正在制作大量的复制品。如果你正在使用任何 源代码分析工具(例如TeamCity中的DuplicateFinder),它将 主要查找您的评论。

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

• 不支持从基类或接口继承文档。 也就是说,任何被重写成员的文档都应该从头开始编写,尽管通常希望至少继承其中的一部分。
• 不支持插入常用文档模板 ,例如此类型为singleton-使用其 <see cref="Instance" /> 属性获取它的唯一实例,甚至初始化它的新实例 <CurrentType> 班

• <inheritdoc />, <inherited /> 标签
• <see cref="..." copy="..." /> 归属于 <see/> 标签

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

最后,还有一个问题 <inheritdoc> 加入 Sandcastle -使用它肯定比复制XML注释要好,但与FiXml相比,它几乎没有缺点:

• Sandcastle生成已编译的HTML帮助文件-它不修改 .xml 文件夹 包含提取的XML注释。但是这些文件被很多工具使用, 包括Visual Studio.NET中的.NET Reflector和class browser\IntelliSense。 因此,如果您只使用Sandcastle,您将不会在那里看到继承的文档。
• Sandcastle的实现没有那么强大。答案是否定的 <see ... copy="true" />

看见 Sandcastle's <inheritdoc> description 详情请参阅。

GhostDoc

如果您只是将文档完全留给继承的方法,或者重写接口方法,会发生什么?我怀疑这取决于你是如何配置NDoc的,但在MSDN文档中,它似乎只是自然地继承了这些文档,并进行了快速检查 暗示 当您不为继承的方法生成文档时,VS不会发出呜呜声。当然值得一试。

我构建了一个命令行工具来对XML文档文件进行后期处理,以添加对<继承doc/>标签

看见 www.inheritdoc.io 详情请参阅(免费版)。