NDoc有一个XML元素inheritdoc,它允许您从父类(或实现的接口)继承成员的文档.但是,Visual Studio(即C#编译器)不理解此标记并抱怨文档不存在或完整.StyleCop和其他一些工具也是如此.有替代方法吗?你如何保持文档完整,但没有重复XML描述?
我有一个更好的答案:FiXml.
使用GhostDoc克隆注释肯定是有效的方法,但它有很多缺点,例如:
当原始注释被更改(在开发期间经常发生)时,其克隆不是.
你正在制作大量的副本.如果您使用任何源代码分析工具(例如Team City中的Duplicate Finder),它将主要找到您的评论.
FiXml的简短描述:它是由C#\ Visual Basic .Net生成的XML文档的后处理器.它作为MSBuild任务实现,因此很容易将它集成到任何项目中.它解决了与使用以下语言编写XML文档相关的一些恼人案例:
不支持从基类或接口继承文档.即任何被覆盖成员的文档都应该从头开始编写,尽管通常至少要继承它的一部分是非常可取的.
不支持插入常用的文档模板,例如"此类型是单例 - 使用其
属性获取它的唯一实例.",甚至"初始化
类的新实例" .
要解决上述问题,请提供以下附加XML标记:
标签
标签中的属性.
这是它的网页和下载页面(断开的链接).
最后,Sandcastle中有
标签 - 使用它比复制XML注释更好,但与FiXml相比它有一些缺点:
Sandcastle生成编译的HTML帮助文件 - 它不会修改.xml
包含提取的XML注释的文件.但是许多工具都使用这些文件,包括.NET Reflector和Visual Studio .NET中的类browser\IntelliSense.因此,如果您只使用Sandcastle,那么您将看不到继承的文档.
Sandcastle的实施功能不那么强大.例如,不是
.
有关详细信息,请参阅Sandcastle的
说明.
另一种方法是使用GhostDoc - 一个Visual Studio的加载项,可以自动为您生成注释.这当然会复制XML描述,这是您要避免的一部分 - 但至少它会自动为您完成.
如果您完全不使用继承的方法或覆盖接口方法,那么会发生什么?我怀疑它取决于你如何配置NDoc,但肯定在MSDN文档中似乎只是自然地继承了文档 - 并且快速检查表明当你不为继承方法生成文档时VS不会发出警告.值得一试,当然.