C#中同步接口和实现注释的方法
是否有自动方法在接口及其实现之间同步注释？ 我目前正在记录它们，并且不想手动使它们保持同步。
更新：
考虑这段代码：
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
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.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（9）
您可以使用 Microsoft Sandcastle（或 NDoc）
inheritdoc标记轻松完成此操作。 它没有得到规范的正式支持，但自定义标签是完全可以接受的，事实上，微软在创建 Sandcastle 时选择从 NDoc 复制这个（以及一两个其他标签）。这里是 Sandcastle 帮助中的帮助页面File Builder GUI，完整描述了其用法。
（当然，正如您的问题所提到的，这并不是专门的“同步”，但它似乎正是您正在寻找的东西。）
作为注释，这对我来说听起来是一个完全公平的想法，尽管我我发现有些人认为您应该始终在派生类和实现类中重新指定注释。 （实际上，我自己在记录我的一个库时就做到了这一点，而且我没有看到任何问题。）注释几乎总是没有任何理由不同，所以为什么不直接继承并以简单的方式来做呢？
编辑：关于您的更新，Sandcastle 也可以为您处理。 Sandcastle 可以输出它用于输入的实际 XML 文件的修改版本，这意味着您可以将此修改版本与您的库 DLL 一起分发，而不是直接由 Visual Studio 构建的版本，这意味着您可以智能感知中的注释以及文档文件（CHM，等等）。
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.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?
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 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).
如果您还没有使用它，我强烈推荐一个名为 GhostDoc 的免费 Visual Studio 插件。 它简化了文档处理过程。 看看我的评论有点相关的问题。
虽然 GhostDoc 不会自动进行同步，但它可以帮助您解决以下情况：
您有一个记录的接口方法。 在类中实现这个接口，按下GhostDoc快捷键
Ctrl-Shift-D，来自接口的XML注释就会被添加到实现的方法中。转到选项-> 键盘设置，并将一个键分配给
GhostDoc.AddIn.RebuildDocumentation（我使用Ctrl-Shift-Alt-D）。现在，如果您更改界面上的XML注释，只需在实现的方法上按此快捷键，文档就会更新。 不幸的是，反之亦然。
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 comment on a somewhat related question.
Although GhostDoc won't make the synchronization automatically, it can help you with the following scenario:
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.Go to the Options -> Keyboard settings, and assign a key to
GhostDoc.AddIn.RebuildDocumentation(I usedCtrl-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.
我通常这样写注释：
这些方法仅由接口使用，因此编码时该注释甚至不会显示在工具提示中。
编辑：
如果你想在直接调用类时查看文档而不是使用接口，，你需要写两次或者使用像GhostDoc这样的工具。
I usually write comments like this:
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 not using the interface, you need to write it twice or use a tool like GhostDoc.
尝试GhostDoc！ 它对我有用:-)
编辑：现在我已经知道 Sandcastle 对
Try GhostDoc! It works for me :-)
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.我有一个更好的答案：FiXml。，我是其作者之一
克隆肯定是可行的方法，但它有明显的缺点，例如：
它的克隆不是。
源代码分析工具（例如 Team City 中的 Duplicate Finder），它将
主要查找您的评论。
正如前面提到的，Sandcastle< 中有
包含提取的 XML 注释的
.xml文件（最后，这是无法完成的编译期间“即时”）。
<参见...copy="true"/>。请参阅 Sandcastle 的
FiXml简介：它是由C#\Visual Basic .Net生成的XML文档的后处理器。 它作为 MSBuild 任务实现，因此很容易将其集成到任何项目中。 它解决了与用这些语言编写 XML 文档相关的一些恼人的情况：
为了解决上述问题，提供了以下附加 XML 标记：
、 <这是其网页和下载页面。
I have a better answer: FiXml., I'm one of its authors
Cloning the is certainly working approach, but it has significant disadvantages, e.g.:
its clone is not.
source code analysis tools (e.g. Duplicate Finder in Team City), it will
find mainly your comments.
As it was mentioned, there is
<inheritdoc>tag in Sandcastle, but it has few disadvantages in comparison to FiXml:.xmlfiles containing extracted XML comments (at last, this can't be done"on the fly" during the compilation).
<see ... copy="true" />.See Sandcastle's
<inheritdoc>description for further details.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:
<see cref="Instance" />property to get the only instance of it.”, or even “Initializes a new instance of<CurrentType>class.”To solve mentioned issues, the following additional XML tags are provided:
<inheritdoc />, <inherited />tags<see cref="..." copy="..." />attribute in<see/>tag.Here is its web page and download page.
阅读此处
使用此
Read here
Use this
我构建了一个库来对 XML 文档文件进行后处理，以添加对的支持。 标签。
虽然它对源代码中的 Intellisense 没有帮助，但它确实允许将修改后的 XML 文档文件包含在 NuGet 包中，因此可以在引用的 NuGet 包中使用 Intellisense。
更多信息请访问 www.inheritdoc.io（提供免费版本）。
I built a library to post-process the XML documentation files to add support for the <inheritdoc/> tag.
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.
More info at www.inheritdoc.io (free version available).
不要那样做。 可以这样想 - 如果两个注释都需要始终相同，那么其中一个注释就没有必要。 评论必须有一个原因（除了某种奇怪的义务来评论阻止每个函数和变量），因此您需要弄清楚这个独特的原因是什么并记录下来。
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.
使用 ReSharper，您可以复制它，但我不认为它始终保持同步。
With ReSharper you can copy it, but I don't think that it is in sync all the time.