.NET xml docs - 继承文档

Question

NDoc有一个XML元素inheritdoc,它允许您从父类(或实现的接口)继承成员的文档.但是,Visual Studio(即C#编译器)不理解此标记并抱怨文档不存在或完整.StyleCop和其他一些工具也是如此.有替代方法吗？你如何保持文档完整,但没有重复XML描述？

Answer 1

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

使用GhostDoc克隆注释肯定是有效的方法,但它有很多缺点,例如:

• 当原始注释被更改(在开发期间经常发生)时,其克隆不是.
• 你正在制作大量的副本.如果您使用任何源代码分析工具(例如Team City中的Duplicate Finder),它将主要找到您的评论.

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

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

要解决上述问题,请提供以下附加XML标记:

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

这是它的网页和下载页面(断开的链接).

最后,Sandcastle中有<inheritdoc>标签 - 使用它比复制XML注释更好,但与FiXml相比它有一些缺点:

• Sandcastle生成编译的HTML帮助文件 - 它不会修改.xml包含提取的XML注释的文件.但是许多工具都使用这些文件,包括.NET Reflector和Visual Studio .NET中的类browser\IntelliSense.因此,如果您只使用Sandcastle,那么您将看不到继承的文档.
• Sandcastle的实施功能不那么强大.例如,不是 <see ... copy="true" />.

有关详细信息,请参阅Sandcastle的<inheritdoc>说明.

Answer 2

另一种方法是使用GhostDoc - 一个Visual Studio的加载项,可以自动为您生成注释.这当然会复制XML描述,这是您要避免的一部分 - 但至少它会自动为您完成.

如果您完全不使用继承的方法或覆盖接口方法,那么会发生什么？我怀疑它取决于你如何配置NDoc,但肯定在MSDN文档中似乎只是自然地继承了文档 - 并且快速检查表明当你不为继承方法生成文档时VS不会发出警告.值得一试,当然.