37

NDoc 有一个 XML 元素inheritdoc，它允许您从父类（或实现的接口）继承成员的文档。然而，Visual Studio（即 C# 编译器）不理解这个标签并抱怨文档不存在或不完整。StyleCop 和其他一些工具也是如此。有替代方法吗？您如何在不重复 XML 描述的情况下保持文档的完整性？

4

3 回答 3

23

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

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

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

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

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

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

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

这是它的网页和下载页面（断开的链接）。

最后， Sandcastle中有<inheritdoc>标签——使用它肯定比复制 XML 注释要好，但与 FiXml 相比它几乎没有缺点：

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

有关详细信息，请参阅Sandcastle 的<inheritdoc>描述。

于 2009-07-03T18:33:10.403 回答
14

一种替代方法是使用GhostDoc - Visual Studio 的一个插件，它会自动为您生成评论。这当然复制了 XML 描述，这是您试图避免的一部分 - 但至少它会自动为您完成。

如果您只为被继承的方法或覆盖接口方法而完全放弃文档会发生什么？我怀疑这取决于您如何配置 NDoc，但肯定在 MSDN 文档中似乎只是自然地继承了文档 - 并且快速检查表明，当您不为继承的方法提供文档时，VS 不会抱怨。值得一试，当然。

于 2008-11-22T20:08:36.497 回答
2

我构建了一个命令行工具来对 XML 文档文件进行后处理，以添加对 <inheritdoc/> 标记的支持。

它对源代码中的 Intellisense 没有帮助，但它确实允许将修改后的 XML 文档文件包含在 NuGet 包中，因此可以在引用的 NuGet 包中与 Intellisense 一起使用。

有关详细信息，请参见www.inheritdoc.io（提供免费版本）。

于 2017-12-20T23:50:03.017 回答