同步方法在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.

更新：

考虑这个code：

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

的＆LT; inheritDoc /方式＆gt; 标记将完全产生沙堡的文件，但它不能在智能感知提示工作

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

请分享您的想法。

感谢。

推荐答案

您可以使用Microsoft沙堡（或NDoc的） inheritdoc 标签做到这一点很容易。这不是正式规范的支持，但自定义标签是完全可以接受的，而事实上微软选择了从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)
{
    //
}

这里是从沙堡帮助文件生成器中的帮助页面图形用户界面，其描述了在满它的使用。

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

作为一个说明，这听起来像一个完全公平的想法对我来说，虽然我还观察到，有些人认为你应该总是respecify在派生和实现的类注释。 （其实我已经做到了我自己在记录我的图书馆之一，我还没有看到任何问题任何责任。）几乎总是没有理由的意见都不同，所以为什么不只是继承和做简单的方法？

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?

编辑：关于您的更新，沙堡也可以照顾你们。沙堡可输出的实际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屋！