C# 的注释继承（实际上是任何语言）
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/342964/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Comment Inheritance for C# (actually any language)
提问by jumpinHymanie
Suppose I have this interface
假设我有这个界面
public interface IFoo
{
///<summary>
/// Foo method
///</summary>
void Foo();
///<summary>
/// Bar method
///</summary>
void Bar();
///<summary>
/// Situation normal
///</summary>
void Snafu();
}
And this class
而这堂课
public class Foo : IFoo
{
public void Foo() { ... }
public void Bar() { ... }
public void Snafu() { ... }
}
Is there a way, or is there a tool that can let me automatically put in the comments of each member in a base class or interface?
有没有办法，或者有什么工具可以让我自动将每个成员的注释放入基类或接口中？
Because I hate re-writing the same comments for each derived sub-class!
因为我讨厌为每个派生的子类重写相同的注释！
采纳答案by James Curran
回答by Dennis
Use /// <inheritdoc/>if you want inheritance. Avoid GhostDoc or anything like that.
/// <inheritdoc/>如果你想要继承，请使用。避免使用 GhostDoc 或类似的东西。
I agree it is annoying that comments are not inherited. It would be a fairly simple add-in to create if someone had the time (i wish i did).
我同意评论没有被继承是很烦人的。如果有人有时间（我希望我有），这将是一个相当简单的插件来创建。
That said, in our code base we put XML comments on the interfaces only and add extra implementation comments to the class. This works for us as our classes are private/internal and only the interface is public. Any time we use the objects via the interfaces we have full comments display in intellisence.
也就是说，在我们的代码库中，我们只在接口上放置了 XML 注释，并向类添加了额外的实现注释。这对我们有用，因为我们的类是私有/内部的，只有接口是公共的。任何时候我们通过接口使用对象时，我们都会在智能中显示完整的注释。
GhostDoc is good start and has made the process easier to write comments. It is especially useful keeping comments up-to-date when you add/remove parameters, re-run GhostDoc and it will update the description.
GhostDoc 是一个良好的开端，并使编写注释的过程变得更容易。当您添加/删除参数、重新运行 GhostDoc 并更新描述时，保持注释是最新的特别有用。
回答by JeffHeaton
Java has this, and I use it all the time. Just do:
Java 有这个，我一直在使用它。做就是了：
/**
* {@inheritDoc}
*/
And the Javadoc tool figures it out.
Javadoc 工具可以解决这个问题。
C# has similar marker:
C# 有类似的标记：
<inheritDoc/>
You can read more here:
你可以在这里阅读更多：
http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm
http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm
回答by svick
Resharper has an option to copy the comments from the base class or interface.
Resharper 可以选择从基类或接口复制注释。
回答by Vadim
You can always use <inheritdoc />tag.
你总是可以使用<inheritdoc />标签。
public class Foo : IFoo
{
/// <inheritdoc />
public void Foo() { ... }
/// <inheritdoc />
public void Bar() { ... }
/// <inheritdoc />
public void Snafu() { ... }
}
回答by Mathias Rotter
Another way is to use the <see />XML documentation tag.
This is some extra effort but works out of the box...
另一种方法是使用<see />XML 文档标记。这是一些额外的努力，但开箱即用......
Here are some examples:
这里有些例子：
/// <summary>
/// Implementation of <see cref="IFoo"/>.
/// </summary>
public class Foo : IFoo
{
/// <summary>
/// See <see cref="IFoo"/>.
/// </summary>
public void Foo() { ... }
/// <summary>
/// See <see cref="IFoo.Bar"/>
/// </summary>
public void Bar() { ... }
/// <summary>
/// This implementation of <see cref="IFoo.Snafu"/> uses the a caching algorithm for performance optimization.
/// </summary>
public void Snafu() { ... }
}
Update:
更新：
I now prefer to use /// <inheritdoc/>which is now supported by ReSharper.
我现在更喜欢使用/// <inheritdoc/>ReSharper 现在支持的。
回答by K Johnson
I ended up creating a tool to post-process the XML documentation files to add support for replacing the <inheritdoc/>tag in the XML documentation files themselves. Available at www.inheritdoc.io(free version available).
我最终创建了一个工具来对 XML 文档文件进行后处理，以添加对替换<inheritdoc/>XML 文档文件本身中的标记的支持。可在www.inheritdoc.io 获得（提供免费版本）。
回答by gatsby
I would say to directly use the
我会说直接使用
/// <inheritdoc cref="YourClass.YourMethod"/> --> For methods inheritance
And
和
/// <inheritdoc cref="YourClass"/> --> For directly class inheritance
You have to put this comments just on the previous line of your class/method
您必须将此注释放在类/方法的前一行
This will get the info of your comments for example from an interface that you have documented like :
例如，这将从您已记录的界面中获取您的评论信息，例如：
/// <summary>
/// This method is awesome!
/// </summary>
/// <param name="awesomeParam">The awesome parameter of the month!.</param>
/// <returns>A <see cref="AwesomeObject"/> that is also awesome...</returns>
AwesomeObject CreateAwesome(WhateverObject awesomeParam);
回答by Konard
Well, there is a kind of native solution, I found for .NET Core 2.2
嗯，有一种本机解决方案，我为 .NET Core 2.2 找到了
The idea is to use <include>tag.
这个想法是使用<include>标签。
You can add <GenerateDocumentationFile>true</GenerateDocumentationFile>your .csproja file.
您可以添加<GenerateDocumentationFile>true</GenerateDocumentationFile>您.csproj的文件。
You might have an interface:
你可能有一个界面：
namespace YourNamespace
{
/// <summary>
/// Represents interface for a type.
/// </summary>
public interface IType
{
/// <summary>
/// Executes an action in read access mode.
/// </summary>
void ExecuteAction();
}
}
And something that inherits from it:
以及从它继承的东西：
using System;
namespace YourNamespace
{
/// <summary>
/// A type inherited from <see cref="IType"/> interface.
/// </summary>
public class InheritedType : IType
{
/// <include file='bin\Release\netstandard2.0\YourNamespace.xml' path='doc/members/member[@name="M:YourNamespace.IType.ExecuteAction()"]/*'/>
public void ExecuteAction() => Console.WriteLine("Action is executed.");
}
}
Ok, it is a bit scary, but it does add the expected elements to the YourNamespace.xml.
好吧，这有点吓人，但它确实将预期的元素添加到YourNamespace.xml.
If you build Debugconfiguration, you can swap Releasefor Debugin the fileattribute of includetag.
如果你建立Debug的配置，你可以换Release为Debug在file属性include标签。
To find a correct member's nameto reference just open generated Documentation.xmlfile.
要找到正确member的name引用，只需打开生成的Documentation.xml文件。
I also assume that this approach requires a project or solution to be build at least twice (first time to create an initial XML file, and the second time to copy elements from it to itself).
我还假设这种方法需要至少构建两次项目或解决方案（第一次创建初始 XML 文件，第二次将元素从它复制到自身）。
The bright side is that Visual Studio validates copied elements, so it is much easier to keep documentation and code in sync with interface/base class, etc (for example names of arguments, names of type parameters, etc).
好的一面是 Visual Studio 验证复制的元素，因此更容易使文档和代码与接口/基类等（例如参数名称、类型参数名称等）保持同步。
At my project, I have ended up with both <inheritdoc/>(for DocFX) and <include/>(For publishing NuGet packages and for validation at Visual Studio):
在我的项目中，我最终得到了<inheritdoc/>（对于 DocFX）和<include/>（对于发布 NuGet 包和在 Visual Studio 进行验证）：
/// <inheritdoc />
/// <include file='bin\Release\netstandard2.0\Platform.Threading.xml' path='doc/members/member[@name="M:Platform.Threading.Synchronization.ISynchronization.ExecuteReadOperation(System.Action)"]/*'/>
public void ExecuteReadOperation(Action action) => action();
