web-dev-qa-db-ja.com

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

基本クラスまたはインターフェイスの各メンバーのコメントを自動的に入力できるツールはありますか？

派生したサブクラスごとに同じコメントを書き直すのは嫌だからです！

c#inheritancecomments
77
jumpinjackie

GhostDoc はまさにそれを行います。継承されないメソッドについては、名前から説明を作成しようとします。

FlingThing()は"Flings the Thing"になります

18
James Curran

いつでも使用できます<inheritdoc />タグ。

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

つかいます /// <inheritdoc/>継承が必要な場合。 GhostDocなどは避けてください。

コメントが継承されないのは面倒です。誰かに時間があれば、作成するのはかなり簡単なアドインになります（できたらいいのに）。

つまり、コードベースでは、インターフェイスにのみXMLコメントを追加し、クラスに実装コメントを追加します。クラスはプライベート/内部であり、インターフェイスのみがパブリックであるため、これは機能します。インターフェイスを介してオブジェクトを使用するときはいつでも、完全なコメントがインテリジェンスで表示されます。

GhostDocは良いスタートであり、コメントを書きやすくしました。パラメーターを追加/削除し、GhostDocを再実行すると、コメントを最新の状態に維持すると、説明が更新されます。

16
Dennis

Javaにはこれがあり、私は常にそれを使用しています。ただやる：

/**
 * {@inheritDoc}
 */

そして、Javadocツールがそれを把握します。

C＃には同様のマーカーがあります。

<inheritDoc/>

詳細はこちらをご覧ください：

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

14
JeffHeaton

Resharperには、基本クラスまたはインターフェイスからコメントをコピーするオプションがあります。

8
svick

私は直接使用すると言います

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

別の方法は、<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でサポートされるようになりました。

5
Mathias Rotter

最終的に、XMLドキュメントファイルを後処理して、XMLドキュメントファイル自体の<inheritdoc/>タグを置き換えるサポートを追加するツールを作成しました。 www.inheritdoc.io （無料バージョンが利用可能）で入手できます。

1
K Johnson

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

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

<GenerateDocumentationFile>true</GenerateDocumentationFile> your .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ファイルを開くだけです。

また、このアプローチでは、プロジェクトまたはソリューションを少なくとも2回ビルドする必要があると仮定します（最初のXMLファイルを作成するのは1回目、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();
0
Konard