当前位置:  开发笔记 > 编程语言 > 正文

.NET xml docs - 继承文档

如何解决《.NETxmldocs-继承文档》经验,为你挑选了2个好方法。

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



1> Alex Yakunin..:

我有一个更好的答案: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的说明.


FiXml现在正式不受支持,并且在VS2013中不能使用,特别是在x64下.稍微使用构建脚本会使它运行,但它实际上不会正常工作,并且无法运行两次.有关更多信息,请访问Xtensive的SO-lookalike帮助网站上的这个问题:http://support.x-tensive.com/question/5419/problem-with-fixml
理论上很好(链接+1),但在实践中我发现FiXml太麻烦不实用.它偶尔会锁定文件,我将不得不重新启动VS以便再次构建.我注意到它将所有引用程序集加载到当前的"AppDomain"中,而不是创建一个单独的"AppDomain",以后可以卸载它.这可能就是原因.

2> Jon Skeet..:

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

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

推荐阅读
殉情放开那只小兔子
这个屌丝很懒,什么也没留下!
DevBox开发工具箱 | 专业的在线开发工具网站    京公网安备 11010802040832号  |  京ICP备19059560号-6
Copyright © 1998 - 2020 DevBox.CN. All Rights Reserved devBox.cn 开发工具箱 版权所有