XML 文档注释与接口和实现类[关闭]

Question

我正在使用以下方式记录程序集 XML 文档注释, ，其中一个 chm 文件将使用创建 沙堡.

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

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

Answer 1

有似乎不适合在沙堡这样autodocumentation任何支持。该沙堡帮助文件生成器虽然实现了定制inheritdoc标签。

从SHFB站点：

  

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

<强>第二更新：根据此工作项时，沙堡“支持” inheritdoc是通过SHFB工具。底线，我想是，SHFB解决您的问题。

Answer 2

我有一个更好的答案： 固定值.

使用 GhostDoc \ AtomineerUtils 克隆注释当然是可行的方法，但它有明显的缺点，例如：

• 当最初的评论更改（在开发过程中经常发生）时，其克隆就不会。
• 您正在生成大量重复项。如果您使用任何源代码分析工具（例如在Team City中重复的Finder），它将主要找到您的评论。

正如所提到的，有 <inheritdoc> 标记在 沙堡, ，但与 FiXml 相比，它有一些缺点：

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

看 沙子城堡 <inheritdoc> 描述 了解更多详情。

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

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

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

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

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

Answer 3

一个工具例如 GhostDoc 可以生成对实现类的文档，当你使用它的键盘快捷键。这并不完全是自动的，但可能有助于防止过多的复制粘贴。

也许可以与脚本automized。

Answer 4

AtomineerUtils将自动为您生成的意见，并拿起现有的过载和重载的基类的文档，节省您的麻烦载荷复制需要的地方的信息。

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