102

是否有自动方法在接口及其实现之间同步注释?我目前正在记录它们,并且不想手动使它们保持同步。

更新:

考虑这段代码:

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 中生成文档,但在智能感知工具提示中不起作用。

请分享你的想法。

谢谢。

4

9 回答 9

64

inheritdoc您可以使用 Microsoft Sandcastle(或 NDoc)标签很容易地做到这一点。规范并未正式支持它,但自定义标签是完全可以接受的,而且微软在创建 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 Help File Builder GUI 的帮助页面,它完整地描述了它的用法。

(当然,正如您的问题所提到的,这并不是专门的“同步”,但它似乎正是您正在寻找的。)

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

编辑:关于您的更新,Sandcastle 也可以为您处理。Sandcastle 可以输出它用于输入的实际 XML 文件的修改版本,这意味着您可以将这个修改版本与您的库 DLL 一起分发,而不是由 Visual Studio 直接构建的版本,这意味着您可以在智能感知以及文档文件(CHM,等等)。

于 2009-05-05T09:21:54.207 回答
14

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

虽然 GhostDoc 不会自动进行同步,但它可以帮助您解决以下情况:

您有一个记录在案的接口方法。在一个类中实现这个接口,按下 GhostDoc 快捷键,Ctrl-Shift-D,接口中的 XML 注释将被添加到实现的方法中。

转到选项-> 键盘设置,然后分配一个键GhostDoc.AddIn.RebuildDocumentation(我用过Ctrl-Shift-Alt-D)。 替代文字

现在,如果你改变了界面上的 XML 注释,只需在实现的方法上按下这个快捷键,文档就会更新。不幸的是,反之亦然。

于 2009-05-05T09:20:07.423 回答
7

我通常会这样写评论:

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

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

编辑:

如果你想在直接调用类而不使用接口的情况下查看文档,则需要编写两次或使用 GhostDoc 之类的工具。

于 2009-05-05T09:14:01.650 回答
4

试试GhostDoc!这个对我有用 :-)

编辑:既然我已经知道 Sandcastle 对 的支持<inheritdoc/>,我支持 Noldorin 的帖子。这是一个更好的解决方案。不过,我仍然普遍推荐 GhostDoc。

于 2009-05-05T09:15:37.060 回答
2

我有一个更好的答案:FiXml, 我是它的作者之一

克隆当然是可行的方法,但它有很大的缺点,例如:

  • 当原始注释被更改时(在开发过程中经常发生),它的克隆不会。
  • 你正在产生大量的重复。如果您使用任何源代码分析工具(例如 Team City 中的 Duplicate Finder),它将主要找到您的评论。

如前所述,Sandcastle<inheritdoc>中有标签,但与 FiXml 相比,它几乎没有缺点:

  • Sandcastle 生成已编译的 HTML 帮助文件 - 通常它不会修改 .xml包含提取的 XML 注释的文件(最后,这不能在编译期间“即时”完成)。
  • Sandcastle 的实现没有那么强大。例如,不是 <see ... copy="true" />

有关详细信息,请参阅Sandcastle 的<inheritdoc>描述

FiXml 的简短描述:它是由 C#\Visual Basic .Net 生成的 XML 文档的后处理器。它是作为 MSBuild 任务实现的,因此很容易将其集成到任何项目中。它解决了一些与用这些语言编写 XML 文档相关的烦人案例:

  • 不支持从基类或接口继承文档。即任何被覆盖的成员的文档都应该从头开始编写,尽管通常至少继承它的一部分是非常可取的。
  • 不支持插入常用的文档模板,例如“这种类型是单例的 - 使用它的<see cref="Instance" />属性来获取它的唯一实例。”,甚至“初始化一个新的<CurrentType>类实例”。</li>

为了解决上述问题,提供了以下附加 XML 标记:

  • <inheritdoc />, <inherited />标签
  • <see cref="..." copy="..." /><see/>标签中的属性。

这是它的网页下载页面

于 2009-07-03T18:45:39.763 回答
1
/// <inheritDoc/>

在这里阅读

用这个

于 2009-05-05T09:24:26.853 回答
1

我构建了一个库来对 XML 文档文件进行后处理,以添加对 <inheritdoc/> 标记的支持。

虽然它对源代码中的 Intellisense 没有帮助,但它确实允许将修改后的 XML 文档文件包含在 NuGet 包中,因此可以在引用的 NuGet 包中与 Intellisense 一起使用。

更多信息请访问www.inheritdoc.io(提供免费版本)。

于 2017-12-20T22:42:33.800 回答
0

不要那样做。这样想——如果要求两条评论始终相同,则不需要其中一条。评论必须有一个原因(除了某种奇怪的义务来评论阻止每个函数和变量)所以你需要弄清楚那个独特的原因是什么并记录下来。

于 2009-05-05T09:13:35.957 回答
0

使用 ReSharper,您可以复制它,但我不认为它一直是同步的。

于 2009-05-05T09:45:14.213 回答