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

98

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.

c#  documentation  xml-documentation 
— Valentin Vasilyev
sumber
— hellboy
Bagaimana cara membuat Atomineer Pro agar dapat menghasilkan tag dokumentasi <inheritDoc /> untuk implementasi jika dokumentasi untuk antarmuka tersedia?
— hellboy
3
Anda benar <inheritdoc/>rusak di Visual Studio. Silakan pilih laporan bug di visualstudio.uservoice.com/forums/121579-visual-studio/…
— Kolonel Panic

Jawaban:

62

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).

— Noldorin
sumber
Hei, itu bagus sekali! Saya suka Sandcastle!
— Tor Haugen
Posting diedit untuk menjawab pertanyaan yang diperbarui.
— Noldorin
2
dapatkah ini dilakukan di tingkat kelas? sehingga saya tidak perlu meletakkan /// <inheritdoc /> sebelum setiap metode.
— Antony Scott
1
Satu hal yang saya perhatikan adalah itu <inheritdoc/> tidak mewarisi dokumentasi untuk <param>tag.
— Stephen
1
Pilih fitur suara pengguna ini agar <inheritdoc /> secara resmi ditambahkan ke spesifikasi C # dan bekerja dengan VS intellisense visualstudio.uservoice.com/forums/121579-visual-studio/…
— deadlydog
14

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). teks alt

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.

— Igal Tabachnik
sumber
Versi terbaru (5.3.16270) dari GhostDoc juga dapat membuat dokumen warisan. Saya baru saja mencobanya untuk implementasi antarmuka saya. Bonus bagus, itu juga menambahkan pengecualian dengan pesan pengecualian yang dilemparkan :-)
— Christoph
6

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.

— Stefan Steinegger
sumber
4

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.

— Tor Haugen
sumber
6
Secara pribadi saya tidak suka GhostDoc. Ini menghasilkan dokumentasi yang sebenarnya tidak ada. Ini menyembunyikan fakta bahwa ada sesuatu yang tidak didokumentasikan. Hanya pendapat pribadi, saya tidak mengatakan bahwa itu adalah sesuatu yang buruk secara umum.
— Stefan Steinegger
1
Setuju dengan komentar dari Stefan bahwa GhostDoc tidak sempurna, namun secara otomatis menarik komentar "mewarisi" seperti ini sehingga ini adalah jawaban yang cukup bagus untuk pertanyaan tersebut.
— Steve
Stefan, saya tidak setuju - sebaliknya, karena GhostDoc hanya mencerminkan dokumentasi yang telah Anda "masukkan" ke dalam nama anggota Anda (dengan membangun prosa dari nama), itu hanya menghasilkan dokumentasi di mana dokumentasinya sudah ada (secara implisit). Karena itu, ia tidak 'menghasilkan' apa-apa, tetapi prosa yang dihasilkan adalah titik awal yang sangat baik di mana Anda dapat menambahkan nilai sebenarnya. Dokumentasi nyata masih membutuhkan beberapa pekerjaan.
— Tor Haugen
2

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 .

— Alex Yakunin
sumber
1

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).

— K Johnson
sumber
0

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.

— 1800 INFORMASI
sumber
3
Saya tidak akan menggunakan antarmuka di sini jika saya tidak memalsukannya dalam pengujian.
— Valentin Vasilyev
0

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

— crauscher
sumber
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.