Warisan Komentar untuk C # (sebenarnya bahasa apa pun)

Misalkan saya memiliki antarmuka ini

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

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

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

Dan kelas ini

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

Adakah cara, atau adakah alat yang memungkinkan saya secara otomatis memasukkan komentar dari setiap anggota di kelas atau antarmuka dasar?

Karena saya benci menulis ulang komentar yang sama untuk setiap sub-kelas turunan!

GhostDoc melakukan hal itu. Untuk metode yang tidak diwariskan, mencoba membuat deskripsi dari namanya.

FlingThing() menjadi "Flings the Thing"

Anda selalu dapat menggunakan <inheritdoc />tag:

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

Dengan menggunakan crefatribut tersebut, Anda bahkan dapat merujuk ke anggota yang sama sekali berbeda di kelas atau namespace yang sama sekali berbeda!

public class Foo
{
    /// <inheritdoc cref="System.String.IndexOf" />
    public void Bar() { ... } // this method will now have the documentation of System.String.IndexOf
}

Gunakan /// <inheritdoc/>jika Anda menginginkan warisan. Hindari GhostDoc atau semacamnya.

Saya setuju bahwa komentar tidak diwariskan adalah hal yang menjengkelkan. Ini akan menjadi tambahan yang cukup sederhana untuk dibuat jika seseorang punya waktu (saya harap saya melakukannya).

Karena itu, dalam basis kode kami, kami meletakkan komentar XML pada antarmuka saja dan menambahkan komentar implementasi tambahan ke kelas. Ini berfungsi untuk kami karena kelas kami bersifat pribadi / internal dan hanya antarmuka yang publik. Setiap kali kita menggunakan objek melalui antarmuka kita memiliki tampilan komentar penuh dalam kecerdasan.

GhostDoc adalah permulaan yang baik dan telah mempermudah proses menulis komentar. Ini sangat berguna untuk menjaga komentar tetap up-to-date ketika Anda menambah / menghapus parameter, menjalankan ulang GhostDoc dan itu akan memperbarui deskripsi.

Java memiliki ini, dan saya menggunakannya sepanjang waktu. Lakukan saja:

/**
 * {@inheritDoc}
 */

Dan alat Javadoc mengetahuinya.

C # memiliki penanda yang mirip:

<inheritDoc/>

Anda dapat membaca lebih lanjut di sini:

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

Saya akan mengatakan untuk langsung menggunakan

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

Dan

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

Anda harus meletakkan komentar ini tepat di baris sebelumnya dari kelas / metode Anda

Ini akan mendapatkan info dari komentar Anda misalnya dari antarmuka yang telah Anda dokumentasikan seperti:

    /// <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 memiliki opsi untuk menyalin komentar dari kelas atau antarmuka dasar.

Cara lain adalah dengan menggunakan <see />tag dokumentasi XML. Ini adalah upaya ekstra tetapi berhasil di luar kotak ...

Berikut beberapa contohnya:

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

Memperbarui:

Saya sekarang lebih suka menggunakan /// <inheritdoc/>yang sekarang didukung oleh ReSharper.

Saya akhirnya membuat alat untuk pasca-proses file dokumentasi XML untuk menambahkan dukungan untuk mengganti <inheritdoc/>tag di file dokumentasi XML itu sendiri. Tersedia di www.inheritdoc.io (tersedia versi gratis).

Ada semacam solusi asli, yang saya temukan untuk .NET Core 2.2

Idenya adalah menggunakan <include>tag.

Anda dapat menambahkan <GenerateDocumentationFile>true</GenerateDocumentationFile>Anda .csprojfile.

Anda mungkin memiliki antarmuka:

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

Dan sesuatu yang diwarisi darinya:

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

Oke, ini agak menakutkan, tetapi menambahkan elemen yang diharapkan ke file YourNamespace.xml.

Jika Anda membangun Debugkonfigurasi, Anda dapat menukar Releaseuntuk Debugdi fileatributinclude tag.

Untuk menemukan yang benar memberIni nameuntuk referensi hanya membuka dihasilkanDocumentation.xml berkas.

Saya juga berasumsi bahwa pendekatan ini memerlukan proyek atau solusi untuk dibangun setidaknya dua kali (pertama kali membuat file XML awal, dan kedua kalinya menyalin elemen darinya ke dirinya sendiri).

Sisi baiknya adalah Visual Studio memvalidasi elemen yang disalin, sehingga jauh lebih mudah untuk menjaga dokumentasi dan kode sinkron dengan antarmuka / kelas dasar, dll (misalnya nama argumen, nama parameter tipe, dll).

Di proyek saya, saya telah berakhir dengan <inheritdoc/>(untuk DocFX) dan <include/>(Untuk menerbitkan paket NuGet dan untuk validasi di 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();