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（利用可能な無料版）。

まあ、ある種のネイティブソリューションがあります。.NETCore 2.2用に見つけました

アイデアは、<include>タグを使用することです。

追加でき<GenerateDocumentationFile>true</GenerateDocumentationFile>ます.csproj Aファイルを。

あなたはインターフェースを持っているかもしれません：

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

OK、少し怖いですが、期待される要素がに追加されますYourNamespace.xml。

あなたが構築する場合Debugの構成を、あなたは入れ替えることができますReleaseのためDebugにfileの属性includeタグ。

正しいを見つけるにはmember「S nameだけ開いて生成された参照するためにDocumentation.xmlファイルを。

また、このアプローチでは、プロジェクトまたはソリューションを少なくとも2回ビルドする必要があると想定しています（最初は最初のXMLファイルを作成し、2回目は要素をファイルからそれ自体にコピーします）。

明るい面は、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();