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

Ways to synchronize interface and implementation comments in C#

提问by Valentin Vasilyev

Are there automatic ways to sync comments between an interface and its implementation? I'm currently documenting them both and wouldn't like to manually keep them in sync.

是否有自动方法在接口及其实现之间同步注释？我目前正在记录它们，不想手动保持它们同步。

UPDATE:

更新：

Consider this code:

考虑这个代码：

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

When I create class like this:

当我创建这样的类时：

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

Here comments are not shown:

这里没有显示注释：

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

The <inheritDoc/>tag will perfectly generate the documentation in Sand Castle, but it doesn't work in intellisense tooltips.

该<inheritDoc/>标签将在 Sand Castle 中完美生成文档，但它在智能感知工具提示中不起作用。

Please share your ideas.

请分享您的想法。

Thanks.

谢谢。

采纳答案by Noldorin

You can do this quite easily using the Microsoft Sandcastle (or NDoc) inheritdoctag. It's not officially supported by the specification, but custom tags are perfectly acceptable, and indeed Microsoft chose to copy this (and one or two other tags) from NDoc when they created Sandcastle.

您可以使用 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)
{
    //
}

Hereis the help page from the Sandcastle Help File Builder GUI, which describes its usage in full.

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

(Of course, this isn't specifically "synchronisation", as your question mentions, but it would seem to be exactly what you're looking for nonetheless.)

（当然，正如您的问题所提到的，这并不是专门的“同步”，但它似乎正是您要寻找的。）

As a note, this sounds like a perfectly fair idea to me, though I've observed that some people think you should always respecify comments in derived and implemented classes. (I've actually done it myself in documenting one of my libraries and I haven't see any problems whatsoever.) There's almost always no reason for the comments to differ at all, so why not just inherit and do it the easy way?

请注意，这对我来说听起来是一个非常合理的想法，尽管我观察到有些人认为您应该始终在派生类和实现类中重新指定注释。（我实际上已经在记录我的一个库时自己完成了它，我没有看到任何问题。）几乎总是没有理由让评论完全不同，那么为什么不直接继承并以简单的方式做到这一点呢？

Edit:Regarding your update, Sandcastle can also take care of that for you. Sandcastle can output a modified version of the actual XML file it uses for input, which means you can distribute this modified versionalong with your library DLL instead of the one built directly by Visual Studio, which means you have the comments in intellisense as well as the documentation file (CHM, whatever).

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

回答by 1800 INFORMATION

Don't do that. Think of it this way - if both comments are required to be the same all the time, then one of them isn't necessary. There has to be a reason for the comment (besides some kind of weird obligation to comment-block every function and variable) so you need to figure out what that unique reason is and document that.

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

回答by Stefan Steinegger

I usually write comments like this:

我通常写这样的评论：

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

The methods are used only by the interface, so this comment is not even shown in tooltips when coding.

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

Edit:

编辑：

If you want to see docs when you call the class directly and notusing the interface, you need to write it twice or use a tool like GhostDoc.

如果想直接调用类而不使用接口的时候看文档，需要写两遍或者使用GhostDoc之类的工具。

回答by Tor Haugen

Try GhostDoc! It works for me :-)

试试GhostDoc！这个对我有用 ：-）

Edit:Now that I've been made aware of Sandcastle's support for <inheritdoc/>, I endorse Noldorin's post. It's a much better solution. I still recommend GhostDoc on a general basis, though.

编辑：既然我已经知道 Sandcastle 对 的支持<inheritdoc/>，我支持 Noldorin 的帖子。这是一个更好的解决方案。不过，我仍然总体上推荐 GhostDoc。

回答by Igal Tabachnik

If you're not using it already, I strongly recommend a free Visual Studio addon called GhostDoc. It eases the documentation process. Have a look at my commenton a somewhat related question.

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

Although GhostDoc won't make the synchronization automatically, it can help you with the following scenario:

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

You have a documented interface method. Implement this interface in a class, press the GhostDoc shortcut key, Ctrl-Shift-D, and the XML comment from the interface will be added to the implemented method.

您有一个文档化的接口方法。在一个类中实现这个接口，按下GhostDoc快捷键，Ctrl-Shift-D，接口的XML注释就会被添加到实现的方法中。

Go to the Options -> Keyboardsettings, and assign a key to GhostDoc.AddIn.RebuildDocumentation(I used Ctrl-Shift-Alt-D).

转到选项 -> 键盘设置，并为GhostDoc.AddIn.RebuildDocumentation（我使用过Ctrl-Shift-Alt-D）分配一个键。

Now, if you change the XML comment on the interface, just press this shortcut key on the implemented method, and the documentation will be updated. Unfortunately, this doesn't work vice-versa.

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

回答by Krzysztof Kozmic

/// <inheritDoc/>

Read here

在这里阅读

Use this

用这个

回答by crauscher

With ReSharper you can copy it, but I don't think that it is in sync all the time.

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

回答by Alex Yakunin

I have a better answer: FiXml., I'm one of its authors

我有一个更好的答案：FiXml。，我是它的作者之一

Cloning the is certainly working approach, but it has significant disadvantages, e.g.:

克隆当然是可行的方法，但它有明显的缺点，例如：

• When the original comment is changed (which frequently happens during development), its clone is not.
• You're producing huge amount of duplicates. If you're using any source code analysis tools (e.g. Duplicate Finder in Team City), it will find mainly your comments.

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

As it was mentioned, there is <inheritdoc>tag in Sandcastle, but it has few disadvantages in comparison to FiXml:

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

• Sandcastle produces compiled HTML help files - normally it does not modify .xmlfiles containing extracted XML comments (at last, this can't be done "on the fly" during the compilation).
• Sandcastle's implementation is less powerful. E.g. the is no <see ... copy="true" />.

• Sandcastle 生成已编译的 HTML 帮助文件 - 通常它不会修改 .xml包含提取的 XML 注释的文件（最后，这不能在编译期间“即时”完成）。
• Sandcastle 的实现不那么强大。例如，不是 <see ... copy="true" />。

See Sandcastle's <inheritdoc>descriptionfor further details.

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

Short description of FiXml: it is a post-processor of XML documentation produced by C# \ Visual Basic .Net. It is implemented as MSBuild task, so it's quite easy to integrate it to any project. It addresses few annoying cases related to writing XML documentation in these languages:

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

• No support for inheriting the documentation from base class or interface.I.e. a documentation for any overridden member should be written from scratch, although normally it's quite desirable to inherit at least the part of it.
• No support for insertion of commonly used documentation templates, such as “This type is singleton - use its <see cref="Instance" />property to get the only instance of it.”, or even “Initializes a new instance of <CurrentType>class.”

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

To solve mentioned issues, the following additional XML tags are provided:

为了解决上述问题，提供了以下额外的 XML 标记：

• <inheritdoc />, <inherited />tags
• <see cref="..." copy="..." />attribute in <see/>tag.

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

Here is its web pageand download page.

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

回答by K Johnson

I built a library to post-process the XML documentation files to add support for the <inheritdoc/> tag.

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

While it doesn't help with Intellisense in source code, it does allow the modified XML documentation files to be included in a NuGet package and therefore works with Intellisense in referenced NuGet packages.

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

More info at www.inheritdoc.io(free version available).

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