Question

是否有自动方式在界面与其实现之间同步注释？我目前正在记录它们，并且不想手动将它们保持同步。

更新：

考虑以下代码：

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

当我创建这样的类时：

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

此处的评论未显示：

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

<inheritDoc/>标记将完美生成Sand Castle中的文档，但它在intellisense工具提示中不起作用。

请分享您的想法。

感谢。

Answer 1

您可以使用Microsoft Sandcastle（或NDoc）inheritdoc标记轻松完成此操作。它没有得到规范的正式支持，但自定义标签是完全可以接受的，事实上，微软选择在创建Sandcastle时从NDoc复制这个（以及一个或两个其他标签）。

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

Here是Sandcastle帮助文件生成器GUI的帮助页面，它完整地描述了它的用法。

（当然，这不是特别的“同步”，正如你的问题所提到的那样，但它似乎正是你正在寻找的东西。）

作为一个注释，这听起来对我来说是一个非常公平的想法，尽管我观察到有些人认为你应该总是在派生和实现的类中重新指定注释。（我实际上是在记录我的一个库时完成的，我没有看到任何问题。）几乎总是没有理由让评论完全不同，那么为什么不继续并以简单的方式去做呢？

编辑：关于您的更新，Sandcastle也可以为您处理。 Sandcastle可以输出用于输入的实际XML文件的修改版本，这意味着您可以将此修改版本与库DLL一起分发，而不是直接由Visual Studio构建，这意味着您拥有intellisense中的注释以及文档文件（CHM，无论如何）。

Answer 2

如果您还没有使用它，我强烈推荐一个名为GhostDoc的免费Visual Studio插件。它简化了文档处理过程。在一个有点相关的问题上查看my comment。

虽然GhostDoc不会自动进行同步，但它可以帮助您解决以下问题：

您有一个记录在案的界面方法。在类中实现此接口，按GhostDoc快捷键Ctrl-Shift-D，接口中的XML注释将添加到已实现的方法中。

转到选项 - ＆gt;键盘设置，并将密钥分配给GhostDoc.AddIn.RebuildDocumentation（我使用Ctrl-Shift-Alt-D）。

现在，如果您更改界面上的XML注释，只需在实现的方法上按下此快捷键，文档就会更新。不幸的是，这不起作用，反之亦然。

Answer 3

我经常写这样的评论：

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

这些方法仅由界面使用，因此编码时工具提示中甚至不会显示此注释。

修改

如果您希望在使用界面直接调用类并且不时查看文档，则需要编写两次或使用GhostDoc之类的工具。

Answer 4

试试GhostDoc！它对我有用： - ）

编辑：现在我已经了解了Sandcastle对<inheritdoc/>的支持，我支持Noldorin的帖子。这是一个更好的解决方案。不过，我仍然会在一般情况下推荐使用GhostDoc。

Answer 5

我有更好的答案： FiXml 。

克隆肯定是有效的方法，但它有明显的缺点，例如：

当原始评论发生变化时（在开发过程中经常发生），它的克隆不是。
你正在制作大量的副本。如果您正在使用任何源代码分析工具（例如Team City中的Duplicate Finder），它会主要找你的意见。

如上所述，Sandcastle 中有<inheritdoc>个标记，但与FiXml相比，它有一些缺点：

Sandcastle生成编译的HTML帮助文件 - 通常不会修改包含提取的XML注释的.xml个文件（最后，无法完成此操作在编辑过程中“在飞行中”。
Sandcastle的实施不那么强大。例如。不是 <see ... copy="true" />。

有关详细信息，请参阅Sandcastle's <inheritdoc> description。

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

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

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

<inheritdoc />, <inherited />标签

<see cref="..." copy="..." />

<see/>

以下是its web page和download page。

Answer 6

/// <inheritDoc/>

Read here

Use this

Answer 7

我构建了一个库来对XML文档文件进行后处理，以添加对＆lt; inheritdoc /＆gt;的支持。标签

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

www.inheritdoc.io的更多信息（提供免费版本）。

Answer 8

使用ReSharper，您可以复制它，但我不认为它一直在同步。

Answer 9

不要那样做。可以这样想 - 如果两个注释都要求始终相同，那么其中一个注释就没有必要了。这个评论必须有一个理由（除了某种奇怪的义务来评论 - 阻止每个函数和变量）所以你需要弄清楚这个独特的原因是什么并记录下来。

在C＃中同步接口和实现注释的方法

9 个答案: