带有接口和实现类的 XML 文档注释 [关闭]答案

【问题标题】：XML Documentation Comments with Interfaces and implementing class(es) [closed]带有接口和实现类的 XML 文档注释 [关闭]
【发布时间】：2010-10-19 13:09:33
【问题描述】：

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

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

我已经为接口添加了文档，有什么方法可以让我自动记录实现类上的相关方法吗？

【问题讨论】：

标签： .net documentation chm xml-documentation

【解决方案1】：

我有一个更好的答案：FiXml。

使用 GhostDoc \ AtomineerUtils 克隆 cmets 确实是可行的方法，但它有很大的缺点，例如：

当原始注释被更改时（在开发过程中经常发生），它的克隆不是。
您正在产生大量重复。如果您使用任何源代码分析工具（例如 Team City 中的 Duplicate Finder），它将主要是找到你的 cmets。

如前所述，Sandcastle中有<inheritdoc>标签，但与FiXml相比，它几乎没有缺点：

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

更多详情请参阅Sandcastle's <inheritdoc> description。

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

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

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

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

这里是its web page 和download page。

【讨论】：

【解决方案2】：

AtomineerUtils 将为您自动生成 cmets，它会从重载和覆盖的基类中提取现有文档，从而为您在需要的地方复制信息省去大量麻烦。

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

【讨论】：

【解决方案3】：

在 Sandcastle 中似乎不支持此类自动文档。 Sandcastle Help File Builder 虽然实现了一个自定义的 inheritdoc 标记。

来自 SHFB 网站：

支持包括标签，它允许您从基础继承文档类型/成员。这是通过实现一个独立的工具，所以它也可以是由其他第三方工具使用和构建脚本。该工具提供超出那些发现的功能提供的构建组件沙堡。

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

【讨论】：

【解决方案4】：

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

也许它可以通过脚本自动化。

【讨论】：

GhostDoc 可以修改参考 xml 文件还是修改实际代码？如果前者是真的，这可以和Sandcastle一起使用......