7

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

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

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

4

4 回答 4

3

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

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

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

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

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

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

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

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

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

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

这是它的网页和下载页面。

于 2009-07-03T18:39:07.930 回答
1

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

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

于 2009-04-15T09:12:52.197 回答
1

Sandcastle 中似乎不支持这种自动文档化。Sandcastle 帮助文件生成器虽然实现了自定义的inheritdoc 标记。

从 SHFB 网站：

包含对 <inheritdoc /> 标记的支持，它允许您从基本类型/成员继承文档。这是通过独立工具实现的，因此其他第三方工具和构建脚本也可以使用它。此工具提供的功能超出了 Sandcastle 提供的构建组件中的功能。

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

于 2009-04-15T09:42:08.350 回答
1

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

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

于 2009-04-28T22:00:39.403 回答