NDoc 有一个 XML 元素 继承文档 它允许您从父类(或实现的接口(interface))继承成员的文档。但是,Visual Studio(即 C# 编译器)不理解此标记并提示文档不存在或不完整。 StyleCop 和其他一些工具也是如此。有替代方法吗?您如何在不重复 XML 描述的情况下保持文档的完整性?
最佳答案
我有更好的答案: FiXml .
使用 GhostDoc 克隆评论当然是可行的方法,但它有很大的缺点,例如:
它的克隆不是。
源代码分析工具(例如 Team City 中的 Duplicate Finder),它将
主要查找您的意见。
FiXml 的简短描述:它是由 C#\Visual Basic .Net 生成的 XML 文档的后处理器。它是作为 MSBuild 任务实现的,因此很容易将其集成到任何项目中。它解决了一些与用这些语言编写 XML 文档相关的烦人案例:
<see cref="Instance" />
属性来获取它的唯一实例。”,甚至“初始化 <CurrentType>
的新实例类(class)。” 为了解决上述问题,提供了以下附加 XML 标记:
<inheritdoc />, <inherited />
标签 <see cref="..." copy="..." />
<see/>
中的属性标签。 这里是 its web page和 download page (断开的链接)。
最后还有
<inheritdoc>
标记 Sandcastle - 使用它肯定比复制 XML 注释更好,但与 FiXml 相比,它几乎没有缺点:.xml
文件包含提取的 XML 注释。但是这些文件被许多工具使用,
包括 .NET Reflector 和类浏览器\Visual Studio .NET 中的 IntelliSense。
因此,如果您只使用 SandcaSTLe,您将看不到继承的文档。
<see ... copy="true" />
. 见 Sandcastle's
<inheritdoc>
description了解更多详情。
关于.NET xml 文档 - 继承文档,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/311363/