带有接口和实现类的XML文档注释

Question

我正在使用XML Documentation Comments记录程序集，使用chm从中创建Sandcastle文件。

我的程序集包含各种接口，每个接口都由一个类实现（在我的场景中，这些是WCF服务）。

我已经在界面中添加了文档，有没有办法让我自动记录实现类的相关方法？

Answer 1

我有更好的答案： FiXml 。

使用GhostDoc \ AtomineerUtils克隆注释肯定是有效的方法，但它有明显的缺点，例如：

• 当原始评论发生变化时（在开发过程中经常发生）， 它的克隆不是。
• 你正在制作大量的副本。如果您正在使用任何 源代码分析工具（例如Team City中的Duplicate Finder），它会 主要找你的意见。

如上所述，Sandcastle 中有<inheritdoc>个标记，但与FiXml相比，它有一些缺点：

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

有关详细信息，请参阅Sandcastle's <inheritdoc> description。

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

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

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

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

以下是its web page和download page。

Answer 2

当您使用键盘快捷键时，GhostDoc等工具可以生成有关实现类的文档。这不是完全自动的，但可以帮助防止过多的复制粘贴。

也许它可以用脚本自动化。

Answer 3

在Sandcastle似乎没有任何对此类自动文档的支持。 Sandcastle Help File Builder虽然实现了自定义inheritdoc标记。

来自SHFB网站：

  

支持包括在内   ＆lt; inheritdoc /＆gt;标签，它允许你   继承基地的文件   类型/成员。这是通过实现的   一个独立的工具，所以它也可以   其他第三方工具使用的   构建脚本。这个工具提供   功能超出了   随附的构建组件   沙堡。

第二次更新：根据this workitem，Sandcastle对“inheritdoc”的“支持”是通过SHFB工具。我想底线是，SHFB解决了你的问题。

Answer 4

AtomineerUtils将为您自动生成注释，并从重载和重写的基类中获取现有文档，从而避免了在需要的地方复制信息时的麻烦。

http://www.atomineer.com/AtomineerUtils.html