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

Posted 2023-02-18

【中文标题】带有接口和实现类的 XML 文档注释 [关闭]

【英文标题】：XML Documentation Comments with Interfaces and implementing class(es) [closed]

【发布时间】：2010-10-19 13:09:33

【问题描述】：

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

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

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

【参考方案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一起使用......