C＃的注释继承（实际上是任何语言）

假设我有这个介面

public interface IFoo
{
    ///<summary>
    /// Foo method
    ///</summary>
    void Foo();

    ///<summary>
    /// Bar method
    ///</summary>
    void Bar();

    ///<summary>
    /// Situation normal
    ///</summary>
    void Snafu();
}

而这个班

public class Foo : IFoo
{
    public void Foo() { ... }
    public void Bar() { ... }
    public void Snafu() { ... }
}

有没有办法，或者有什么工具可以让我自动在基类或接口中加入每个成员的注释？

因为我讨厌为每个派生子类重写相同的注释！

GhostDoc正是这样做的。对于未继承的方法，它将尝试根据名称创建描述。

FlingThing() 变成 "Flings the Thing"

您可以随时使用<inheritdoc />标签。

public class Foo : IFoo
{
    /// <inheritdoc />
    public void Foo() { ... }
    /// <inheritdoc />
    public void Bar() { ... }
    /// <inheritdoc />
    public void Snafu() { ... }
}

/// <inheritdoc/>如果要继承，请使用。避免使用GhostDoc或类似的东西。

我同意注释不被继承是令人讨厌的。如果有人有时间（我希望我有时间），这将是一个非常简单的外接程序。

就是说，在我们的代码库中，我们仅将XML注释放在接口上，并向该类添加额外的实现注释。这对我们有用，因为我们的课程是私有/内部的，并且只有接口是公共的。每当我们通过界面使用对象时，我们都会以智能方式显示完整的注释。

GhostDoc是一个良好的开端，它使编写注释的过程更加容易。在添加/删除参数，重新运行GhostDoc并更新描述时，使注释保持最新尤其有用。

Java有此功能，我一直都在使用它。做就是了：

/**
 * {@inheritDoc}
 */

Javadoc工具可以解决这个问题。

C＃具有类似的标记：

<inheritDoc/>

你可以在这里阅读更多：

http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm

我会说直接使用

/// <inheritdoc cref="YourClass.YourMethod"/>  --> For methods inheritance

和

/// <inheritdoc cref="YourClass"/>  --> For directly class inheritance

您必须将此注释放在课程/方法的前一行

例如，这将从您已记录的界面中获取评论信息：

    /// <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);

Resharper可以选择从基类或接口复制注释。

另一种方法是使用<see />XML文档标签。这是一项额外的工作，但可以立即使用...

这里有些例子：

/// <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() { ... }
}

更新：

我现在更喜欢使用/// <inheritdoc/>ReSharper支持的功能。

我最终创建了一个对XML文档文件进行后处理的工具，以添加对替换<inheritdoc/>XML文档文件本身中的标记的支持。可从www.inheritdoc.io获得（提供免费版本）。

好吧，我找到了一种针对.NET Core 2.2的本地解决方案

这个想法是使用<include>标签。

您可以添加<GenerateDocumentationFile>true</GenerateDocumentationFile>您的.csproj文件。

您可能有一个接口：

namespace YourNamespace
{
    /// <summary>
    /// Represents interface for a type.
    /// </summary>
    public interface IType
    {
        /// <summary>
        /// Executes an action in read access mode.
        /// </summary>
        void ExecuteAction();
    }
}

从中继承的东西：

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.");
    }
}

好的，这有点吓人，但是确实将预期的元素添加到中YourNamespace.xml。

如果你建立Debug的配置，你可以换Release为Debug在file属性include标签。

要找到正确member的name引用，只需打开生成的Documentation.xml文件即可。

我还假设这种方法要求一个项目或解决方案至少要构建两次（第一次创建一个初始XML文件，第二次将元素从其复制到自身）。

好的一面是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();