Cara untuk menyinkronkan antarmuka dan implementasi komentar di C # [closed]

Apakah ada cara otomatis untuk menyinkronkan komentar antara antarmuka dan implementasinya? Saat ini saya mendokumentasikan keduanya dan tidak ingin menyinkronkan keduanya secara manual.

MEMPERBARUI:

Pertimbangkan kode ini:

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

Saat saya membuat kelas seperti ini:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

Di sini komentar tidak ditampilkan:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

The <inheritDoc/>tag sempurna akan menghasilkan dokumentasi di Sand Castle, tetapi tidak bekerja di tooltips intellisense.

Silakan bagikan ide Anda.

Terima kasih.

Anda dapat melakukan ini dengan mudah menggunakan inheritdoctag Microsoft Sandcastle (atau NDoc) . Ini tidak secara resmi didukung oleh spesifikasinya, tetapi tag kustom dapat diterima dengan sempurna, dan memang Microsoft memilih untuk menyalin ini (dan satu atau dua tag lainnya) dari NDoc ketika mereka membuat Sandcastle.

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

Berikut adalah halaman bantuan dari GUI Bantuan File Builder Sandcastle, yang menjelaskan penggunaannya secara lengkap.

(Tentu saja, ini bukan "sinkronisasi" secara spesifik, seperti yang disebutkan dalam pertanyaan Anda, tetapi tampaknya itulah yang Anda cari.)

Sebagai catatan, ini terdengar seperti ide yang sangat adil bagi saya, meskipun saya telah mengamati bahwa beberapa orang berpikir Anda harus selalu menghargai komentar di kelas yang diturunkan dan diimplementasikan. (Saya sebenarnya telah melakukannya sendiri dalam mendokumentasikan salah satu perpustakaan saya dan saya tidak melihat masalah apa pun.) Hampir selalu tidak ada alasan untuk komentar berbeda sama sekali, jadi mengapa tidak mewarisi dan melakukannya dengan cara yang mudah?

Sunting: Mengenai pembaruan Anda, Sandcastle juga dapat mengurusnya untuk Anda. Sandcastle dapat mengeluarkan versi modifikasi dari file XML sebenarnya yang digunakannya untuk input, yang berarti Anda dapat mendistribusikan versi modifikasi ini bersama dengan DLL library Anda alih-alih versi yang dibuat langsung oleh Visual Studio, yang berarti Anda memiliki komentar di intellisense serta file dokumentasi (CHM, apa pun).

Jika Anda belum menggunakannya, saya sangat menyarankan addon Visual Studio gratis yang disebut GhostDoc . Ini memudahkan proses dokumentasi. Lihat komentar saya tentang pertanyaan yang agak terkait.

Meskipun GhostDoc tidak akan membuat sinkronisasi secara otomatis, ini dapat membantu Anda dengan skenario berikut:

Anda memiliki metode antarmuka yang didokumentasikan. Implementasikan antarmuka ini di sebuah kelas, tekan tombol pintas GhostDoc Ctrl-Shift-D, dan komentar XML dari antarmuka akan ditambahkan ke metode yang diimplementasikan.

Pergi ke Options -> Keyboard settings, dan tetapkan kunci untuk GhostDoc.AddIn.RebuildDocumentation(saya gunakan Ctrl-Shift-Alt-D).

Sekarang, jika Anda mengubah komentar XML pada antarmuka , cukup tekan tombol pintas ini pada metode yang diterapkan, dan dokumentasi akan diperbarui. Sayangnya, ini tidak berfungsi sebaliknya.

Saya biasanya menulis komentar seperti ini:

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

Metode ini hanya digunakan oleh antarmuka, jadi komentar ini bahkan tidak ditampilkan dalam keterangan alat saat melakukan pengkodean.

Edit:

Jika Anda ingin melihat dokumen saat Anda memanggil kelas secara langsung dan tidak menggunakan antarmuka, Anda perlu menulisnya dua kali atau menggunakan alat seperti GhostDoc.

Coba GhostDoc ! Ini bekerja untuk saya :-)

Sunting: Sekarang saya telah diberi tahu tentang dukungan Sandcastle <inheritdoc/>, saya mendukung posting Noldorin. Ini solusi yang jauh lebih baik. Saya masih merekomendasikan GhostDoc secara umum.

Saya punya jawaban yang lebih baik: FiXml . , Saya salah satu penulisnya

Kloning tentu saja merupakan pendekatan yang berhasil, tetapi memiliki kerugian yang signifikan, misalnya:

• Ketika komentar asli diubah (yang sering terjadi selama pengembangan), klonnya tidak.
• Anda menghasilkan duplikat dalam jumlah besar. Jika Anda menggunakan alat analisis kode sumber apa pun (misalnya, Duplikat Finder di Kota Tim), itu akan menemukan sebagian besar komentar Anda.

Seperti yang telah disebutkan, ada <inheritdoc>tag di Sandcastle , tetapi memiliki sedikit kekurangan dibandingkan dengan FiXml:

• Sandcastle membuat file bantuan HTML terkompilasi - biasanya tidak memodifikasi .xmlfile yang berisi komentar XML yang diekstrak (akhirnya, ini tidak dapat dilakukan "dengan cepat" selama kompilasi).
• Implementasi Sandcastle kurang kuat. Misalnya tidak ada <see ... copy="true" />.

Lihat deskripsi Sandcastle<inheritdoc> untuk detail lebih lanjut.

Deskripsi singkat FiXml: ini adalah pasca-prosesor dari dokumentasi XML yang diproduksi oleh C # \ Visual Basic .Net. Ini diimplementasikan sebagai tugas MSBuild, jadi sangat mudah untuk mengintegrasikannya ke proyek apa pun. Ini membahas beberapa kasus yang mengganggu terkait dengan penulisan dokumentasi XML dalam bahasa berikut:

• Tidak ada dukungan untuk mewarisi dokumentasi dari kelas dasar atau antarmuka. Yaitu, dokumentasi untuk setiap anggota yang diganti harus ditulis dari awal, meskipun biasanya cukup diinginkan untuk mewarisi setidaknya sebagian darinya.
• Tidak ada dukungan untuk penyisipan template dokumentasi yang umum digunakan , seperti "Tipe ini tunggal - gunakan <see cref="Instance" />propertinya untuk mendapatkan satu-satunya instance", atau bahkan "Menginisialisasi instance <CurrentType>kelas baru".

Untuk mengatasi masalah yang disebutkan, tag XML tambahan berikut disediakan:

• <inheritdoc />, <inherited /> tag
• <see cref="..." copy="..." />atribut dalam <see/>tag.

Ini adalah halaman web dan halaman unduhannya .

/// <inheritDoc/>

Baca disini

Gunakan ini

Saya membangun perpustakaan untuk memproses file dokumentasi XML untuk menambahkan dukungan untuk tag <inheritdoc />.

Meskipun tidak membantu Intellisense dalam kode sumber, ia mengizinkan file dokumentasi XML yang dimodifikasi untuk disertakan dalam paket NuGet dan oleh karena itu bekerja dengan Intellisense dalam paket NuGet yang direferensikan.

Info lebih lanjut di www.inheritdoc.io (tersedia versi gratis).

Jangan lakukan itu. Anggap saja seperti ini - jika kedua komentar harus sama sepanjang waktu, maka salah satunya tidak perlu. Pasti ada alasan untuk komentar tersebut (selain semacam kewajiban aneh untuk memblokir komentar setiap fungsi dan variabel) jadi Anda perlu mencari tahu alasan unik itu dan mendokumentasikannya.

Dengan ReSharper Anda dapat menyalinnya, tetapi menurut saya itu tidak selalu sinkron.