且构网

分享程序员开发的那些事...
且构网 - 分享程序员编程开发的那些事

同步方法在C#接口和实现评论

更新时间:2022-05-22 21:47:44

您可以使用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).