在C＃中同步接口和实现注释的方法 [英] Ways to synchronize interface and implementation comments in C#

问题描述

是否有自动的方式在界面和实现之间同步注释？
我目前正在记录他们，不想手动保持同步。

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.

更新：

考虑这个代码：

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中的文档，但在智能工具提示中不起作用。

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

请分享你的想法。

谢谢。

推荐答案

可以使用Microsoft Sandcastle（或NDoc） inheritdoc 标签轻松地做到这一点。它不是规范的正式支持，但是自定义标签是完全可以接受的，而且当他们创建Sandcastle时，微软选择从NDoc复制（和一个或两个其他标签）。

You can do this quite easily using the Microsoft Sandcastle (or NDoc) inheritdoc tag. 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.

/// <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)
{
    //
}

这里是来自Sandcastle帮助文件生成器GUI的帮助页面，它描述了它的使用情况。

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

（当然这不是具体的同步，因为你的问题提及，但它似乎正是您正在寻找的东西。）

(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?

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

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 version along 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).

这篇关于在C＃中同步接口和实现注释的方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！