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

Question

是否有自动方式在界面与其实现之间同步注释？我目前正在记录它们,并且不想手动保持它们同步.

更新:

考虑以下代码:

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/>标签将完全产生沙堡的文件,但它并没有在智能感知提示工作.

请分享您的想法.

谢谢.

Answer 1

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

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

(当然,这不是特别"同步",正如你的问题所提到的那样,但它似乎正是你正在寻找的东西.)

作为一个注释,这听起来对我来说是一个非常公平的想法,尽管我观察到有些人认为你应该总是在派生和实现的类中重新指定注释.(我实际上是在记录我的一个库时完成的,我没有看到任何问题.)几乎总是没有理由让评论完全不同,那么为什么不继续并以简单的方式去做呢？

编辑:关于您的更新,Sandcastle也可以为您处理.Sandcastle可以输出用于输入的实际XML文件的修改版本,这意味着您可以将此修改后的版本与库DLL一起分发,而不是由Visual Studio直接构建,这意味着您可以在intellisense中同时使用文档文件(CHM,无论如何).

Answer 2

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

虽然GhostDoc不会自动进行同步,但它可以帮助您完成以下场景:

您有一个记录的接口方法.在类中实现此接口,按GhostDoc快捷键Ctrl-Shift-D,并将界面中的XML注释添加到已实现的方法中.

转到选项 - >键盘设置,然后为GhostDoc.AddIn.RebuildDocumentation(我使用过Ctrl-Shift-Alt-D)指定一个键. 替代文字http://i44.tinypic.com/10dd1f9.png

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

Answer 3

我经常写这样的评论:

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

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

编辑:

如果要在直接调用类而不使用接口时查看文档,则需要编写两次或使用GhostDoc之类的工具.