在C＃中同步接口和实现注释的方法[关闭]

问题描述 投票：86回答：9

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

更新：

考虑以下代码：

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中的文档，但它在intellisense工具提示中不起作用。

请分享您的想法。

谢谢。

c# documentation xml-documentation
9个回答
57
投票

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

Here是Sandcastle帮助文件生成器GUI的帮助页面，它完整地描述了它的用法。

（当然，这不是特别“同步”，正如你的问题所提到的那样，但它似乎正是你正在寻找的东西。）

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

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

11
投票

如果你还没有使用它，我强烈推荐一个名为GhostDoc的免费Visual Studio插件。它简化了文档处理过程。在一个有点相关的问题上看看my comment。

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

您有一个文档化的界面方法。在类中实现此接口，按GhostDoc快捷键Ctrl-Shift-D，接口中的XML注释将添加到已实现的方法中。

转到选项 - >键盘设置，并为GhostDoc.AddIn.RebuildDocumentation指定一个键（我使用了Ctrl-Shift-Alt-D）。 alt text

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

5
投票

我经常写这样的评论：

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

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

编辑：

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

4
投票

试试GhostDoc！这个对我有用 ：-）

编辑：既然我已经意识到Sandcastle对<inheritdoc/>的支持，我支持Noldorin的帖子。这是一个更好的解决方案。不过，我仍然会在一般情况下推荐GhostDoc。

2
投票

我有一个更好的答案：FiXml。，我是它的作者之一

克隆肯定是工作方法，但它有明显的缺点，例如：

  • 当原始注释被更改（在开发期间经常发生）时，其克隆不是。
  • 你正在制作大量的副本。如果您使用任何源代码分析工具（例如Team City中的Duplicate Finder），它将主要找到您的评论。

如上所述，<inheritdoc>中有Sandcastle标签，但与FiXml相比，它有一些缺点：

  • Sandcastle生成编译的HTML帮助文件 - 通常它不会修改包含提取的XML注释的.xml文件（最后，这在编译期间无法“动态”完成）。
  • Sandcastle的实施功能不那么强大。例如。这不是<see ... copy="true" />。

有关详细信息，请参阅Sandcastle's <inheritdoc> description。

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

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

要解决上述问题，请提供以下附加XML标记：

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

这是its web page和download page。

1
投票
/// <inheritDoc/>

Read here

Use this

1
投票

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

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

更多信息，请访问www.inheritdoc.io（免费版）。

0
投票

不要那样做。可以这样想 - 如果两个注释都要求始终相同，那么其中一个注释就没有必要了。评论必须有一个理由（除了某种奇怪的义务来评论 - 阻止每个函数和变量），所以你需要弄清楚这个独特的原因是什么并记录下来。

0
投票

使用ReSharper，您可以复制它，但我不认为它一直在同步。

最新问题
© www.soinside.com 2019 - 2024. All rights reserved.