.net - 带有接口(interface)和实现类的 XML 文档注释

Question

关闭。这个问题需要更多 focused .它目前不接受答案。












想改进这个问题？更新问题，使其仅关注一个问题 editing this post .

4年前关闭。




Improve this question




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

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

我已经在接口(interface)中添加了文档，有什么方法可以自动记录实现类的相关方法吗？

Answer 1

我有更好的答案: FiXml .

使用 GhostDoc\AtomineerUtils 克隆评论当然是可行的方法，但它有很大的缺点，例如:

当原始注释发生更改时(在开发过程中经常发生)，
它的克隆不是。

你正在产生大量的重复。如果您使用任何
源代码分析工具(例如 Team City 中的 Duplicate Finder)，它将
主要查找您的意见。

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

SandcaSTLe 生成已编译的 HTML 帮助文件 - 它不会修改 .xml文件
包含提取的 XML 注释。但是这些文件被许多工具使用，
包括 .NET Reflector 和类浏览器\Visual Studio .NET 中的 IntelliSense。
因此，如果您只使用 SandcaSTLe，您将看不到继承的文档。

SandcaSTLe 的实现没有那么强大。例如。没有<see ... copy="true" /> .

见 Sandcastle's <inheritdoc> description了解更多详情。

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

不支持从基类或接口(interface)继承文档。 IE。任何被覆盖的成员的文档都应该从头开始编写，尽管通常至少继承它的一部分是非常可取的。

不支持插入常用文档模板 ，例如“这种类型是单例的 - 使用它的 <see cref="Instance" />属性来获取它的唯一实例。”，甚至“初始化 <CurrentType> 的新实例类(class)。”

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

<inheritdoc />, <inherited />标签

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

这里是 its web page和 download page .