.NET xml 文档 - 继承文档
NDoc 有一个 XML 元素 inheritdoc，它允许您从父类（或实现的接口）继承成员的文档。 但是，Visual Studio（即 C# 编译器）不理解此标记，并抱怨文档不存在或不完整。 StyleCop 和其他一些工具也是如此。 有替代方法吗？ 如何在不重复 XML 描述的情况下保持文档完整？
NDoc has an XML element inheritdoc which allows you to inherit documentation of a member from the parent class (or an implemented interface). However, Visual Studio (i.e. the C# compiler) does not understand this tag and complains about the documentation not being present or complete. So does StyleCop and some other tools. Is there an alternative approach? How do you go about keeping the docs complete, yet without duplicating the XML descriptions?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（3）
我有一个更好的答案：FiXml。
使用 GhostDoc 克隆注释当然是可行的方法，但它有明显的缺点，例如：
它的克隆不是。
源代码分析工具（例如 Team City 中的 Duplicate Finder），它将
主要查找您的评论。
FiXml简介：它是由C#\Visual Basic .Net生成的XML文档的后处理器。 它作为 MSBuild 任务实现，因此很容易将其集成到任何项目中。 它解决了与用这些语言编写 XML 文档相关的一些恼人的情况：
为了解决上述问题，提供了以下附加 XML 标记：
、 <这是其网页和下载页面（损坏的链接）。
最后，Sandcastle 中有
.xml文件包含提取的 XML 注释。 但这些文件被许多工具使用，
包括 Visual Studio .NET 中的 .NET Reflector 和类浏览器 \ IntelliSense。
因此，如果您只使用 Sandcastle，您将不会在那里看到继承的文档。
<参见...copy="true"/>。请参阅 Sandcastle 的
I have a better answer: FiXml.
Cloning comments with GhostDoc is certainly working approach, but it has significant disadvantages, e.g.:
its clone is not.
source code analysis tools (e.g. Duplicate Finder in Team City), it will
find mainly your comments.
Short description of FiXml: it is a post-processor of XML documentation produced by C# \ Visual Basic .Net. It is implemented as MSBuild task, so it's quite easy to integrate it to any project. It addresses few annoying cases related to writing XML documentation in these languages:
<see cref="Instance" />property to get the only instance of it.”, or even “Initializes a new instance of<CurrentType>class.”To solve mentioned issues, the following additional XML tags are provided:
<inheritdoc />, <inherited />tags<see cref="..." copy="..." />attribute in<see/>tag.Here is its web page and download page (broken links).
Finally, there is
<inheritdoc>tag in Sandcastle - it's definitely better to use it than to copy XML comments, but it has few disadvantages in comparison to FiXml:.xmlfilescontaining extracted XML comments. But these files are used by many tools,
including .NET Reflector and class browser \ IntelliSense in Visual Studio .NET.
So if you use just Sandcastle, you won't see inherited documentation there.
<see ... copy="true" />.See Sandcastle's
<inheritdoc>description for further details.一种替代方法是使用 GhostDoc - 一个 Visual Studio 插件，可以自动为您生成注释。 当然，这会重复 XML 描述，这是您试图避免的事情的一部分 - 但至少它会自动为您完成它。
如果您完全忽略正在继承的方法或重写接口方法的文档，会发生什么？ 我怀疑这取决于你如何配置 NDoc，但当然在 MSDN 文档中似乎只是自然地继承了文档 - 并且快速检查建议当你不提供时 VS 不会抱怨继承方法的文档。 当然值得一试。
One alternative is to use GhostDoc - an add-in for Visual Studio that automatically generates comments for you. This duplicates the XML description of course, which is part of what you're trying to avoid - but at least it does it automatically for you.
What happens if you just leave off the docs entirely for methods which are being inherited, or overriding interface methods? I suspect it depends on how you've got NDoc configured, but certainly in MSDN documentation seems to just naturally inherit the docs - and a quick check suggests that VS won't whinge when you don't prodive docs for an inherited method. Worth a try, certainly.
我构建了一个命令行工具来对 XML 文档文件进行后处理，以添加对的支持。 标签。
它对源代码中的 Intellisense 没有帮助，但它允许将修改后的 XML 文档文件包含在 NuGet 包中，因此可以在引用的 NuGet 包中使用 Intellisense。
有关详细信息，请参阅 www.inheritdoc.io（提供免费版本）。
I built a command line tool to post-process the XML documentation files to add support for the <inheritdoc/> tag.
It doesn't help with Intellisense in source code but it does allow the modified XML documentation files to be included in a NuGet package and therefore works with Intellisense in referenced NuGet packages.
See www.inheritdoc.io for details (free version available).