Visual Studio Menonaktifkan Peringatan Komentar XML yang Hilang

198

Saya punya proyek dengan lebih dari 500 Missing XML Commentperingatan. Saya tahu saya bisa menghapus fitur Komentar XML, atau menempelkan potongan komentar kosong di mana-mana, tapi saya lebih suka solusi umum di mana saya bisa melakukan satu perubahan yang menonaktifkan semua peringatan jenis ini.

Apa yang saya lakukan sekarang adalah meletakkan

///<Summary>
/// 
///</Summary>

atau 

#pragma warning disable 1591

hanya ingin tahu apakah itu mungkin.

visual-studio-2010 xml-comments Nivid Dholakia
sumber
3
Apa pertanyaan sebenarnya? Apakah Anda ingin tahu cara lain untuk menonaktifkan peringatan yang dihasilkan ketika komentar XML hilang? Dalam properti proyek, ubah ke tab "Build" dan hapus centang "file dokumentasi XML". Namun, saya menyarankan untuk tidak menekan peringatan tetapi untuk menambahkan dokumentasi yang hilang.
Gorgsenegger
Itu benar sekali tetapi hanya ingin tahu bagaimana jika kita dapat menyelesaikan ini dari satu tempat karena saya masih baru dalam hal ini.
Nivid Dholakia
Pertanyaan-pertanyaan terkait ini dapat membantu: stackoverflow.com/questions/11444631/... stackoverflow.com/questions/3630282/…
Mightymuke
1
Peringatan hanya muncul untuk anggota yang dapat dilihat oleh majelis lain. Seringkali orang membuat kelas (dan antarmuka, enum, dll.) publicTanpa alasan yang bagus. Dalam hal ini perbaikan yang mudah (dan menurut saya bagus) adalah dengan hanya menghapus kata public(atau menggantinya dengan internalkata kunci yang berlebihan , tergantung pada gaya yang disukai) dari jenis penutup terluar. Lalu semua peringatan CS1591 tentang jenis ini dan anggotanya menghilang. Tentu saja Anda masih harus menyimpan beberapa jenis public. Tetapi dalam kasus itu wajar bahwa Anda perlu mendokumentasikan bagian publik mereka dengan benar.
Jeppe Stig Nielsen

Jawaban:

318

Seperti yang disarankan di atas, secara umum saya tidak berpikir bahwa peringatan ini harus diabaikan (ditekan). Untuk meringkas, cara-cara di sekitar peringatan itu adalah untuk:

  • Menekan peringatan dengan mengubah proyek Properties> Build> Errors and warnings> Suppress warningsdengan memasukkan 1591
  • Tambahkan tag dokumentasi XML ( GhostDoc bisa sangat berguna untuk itu)
  • Menekan peringatan melalui opsi kompiler
  • Hapus tanda centang pada "XML dokumentasi file" kotak centang dalam proyek Properties> Build>Output
  • Tambahkan #pragma warning disable 1591di bagian atas file masing-masing dan #pragma warning restore 1591di bagian bawah
Gorgsenegger
sumber
178
Tolong, tolong jangan gunakan GhostDoc. Jika komentar dapat disimpulkan dari nama metode, maka dapat disimpulkan lebih baik oleh manusia. Ini menambah nilai nol. Waktu itu akan lebih baik dihabiskan untuk memberi selamat pada diri sendiri atas metode yang disebut dengan baik.
JRoughan
24
Saya harus tidak setuju, GhostDoc membantu saya dengan cepat menambahkan daftar paramaters yang diperlukan dan tag kembali (jika metode ini tidak batal). Saya menggunakan dan menyukainya, dan saya tahu beberapa orang lain yang juga menyukainya. Memang benar, bahwa deskripsi dalam ringkasan mungkin perlu diedit, tetapi ini diperhitungkan untuk sebagian besar automatisme dalam kasus tersebut.
Gorgsenegger
32
Jika semua itu dilakukan adalah menambahkan placeholder, itu akan menjadi penghemat waktu yang menyenangkan, tetapi jumlah basis kode yang saya lihat di mana pengembang meninggalkan teks yang dihasilkan membuat kami merasa kami tidak cukup matang secara kolektif untuk menggunakannya. Komentar adalah kruk (sering diperlukan) untuk kode yang tidak mendokumentasikan diri sendiri dan dengan menawarkan pintasan, alat ini memiliki manfaat bersih negatif pada kode dunia.
JRoughan
25
@JRoughan: Saya sepenuhnya setuju. Bagian terburuknya adalah, ketika Anda akhirnya menemukan waktu untuk mendokumentasikan kode Anda dengan benar, alat-alat ini membuat tidak mungkin untuk mengatakan seberapa lengkap cakupan dokumentasi Anda yang sebenarnya. Alat apa pun yang menghitung cakupan dokumentasi akan selalu dibaca 100%. Jadi Anda benar-benar harus melalui tugas yang melelahkan secara mental membaca setiap komentar XML dan mengevaluasi apakah cukup untuk mendokumentasikan kode. Setelah melakukan ini pada proyek besar, saya dapat memberitahu Anda, itu tidak menyenangkan sama sekali. Tolong orang-orang! Jangan gunakan alat dokumentasi otomatis ini!
HiredMind
36
@Gorgsenegger: Tidak dalam kasus ini. Bukan alat yang cacat, itu seluruh konsep. VS2012 menambahkan metode / parameter bertopik ke komentar XML standar jika itu yang Anda inginkan. Tetapi menambahkan komentar yang hanya versi yang lebih panjang dari nama metode dan menyebutnya dokumentasi hanyalah kekacauan visual.
HiredMind
74

Nonaktifkan peringatan: Buka Properti proyek (Klik kanan pada proyek Anda dan pilih Properti dari menu konteks) Buka tab Bangun masukkan deskripsi gambar di sini

Tambahkan 1591 ke kotak teks peringatan Suppress masukkan deskripsi gambar di sini

Rao Adnan
sumber
4
Bekerja seperti pesona dengan daftar yang dipisah koma: "S125, CS1591, S1172". Setelah membangun, peringatan menghilang.
AFD
9
Terima kasih telah menjawab pertanyaan dan tidak memberi kuliah tentang apakah akan menekan peringatan atau tidak!
Dal
31

Anda juga dapat memodifikasi .csprojfile proyek Anda untuk memasukkan <noWarn>1591</noWarn>tag di dalam yang pertama <PropertyGroup>. Berasal dari Artikel Alexandru Bucur Di Sini

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <NoWarn>1591</NoWarn>
  </PropertyGroup>
  ...
</Project>
DotNetPadawan
sumber
3
Ini harus menjadi jawaban untuk hari ini.
Edgar Salazar
3
Sepakat. Sebagian besar jawaban tidak bekerja dengan editor lain, seperti Visual Studio Code.
Krzysztof Czelusniak
9

Pergilah ke properti proyek dan hapus centang opsi menghasilkan dokumen XML.

Hapus centang file dokumentasi XML

Kompilasi ulang dan peringatan akan hilang.

Chris
sumber
2
Ini adalah pendekatan yang baik selama Anda tidak perlu membuat dokumen XML dan Anda tidak keberatan bahwa komentar XML tidak akan divalidasi.
Keith
1
Ini tidak berfungsi jika Anda ingin menyimpan peringatan dari file yang tidak dibuat secara otomatis. Menghapus semua peringatan hanya untuk menghilangkan sebagian peringatan tampaknya agak berlebihan bagi saya. Selain itu, di sebagian besar perusahaan, adalah praktik umum untuk benar-benar membuat komentar XML di semua file yang tidak berisi kode yang dibuat secara otomatis. Selain itu, pengguna meminta solusi yang tidak hanya menghapus fitur komentar XML, jadi ini tidak menjawab pertanyaan.
SubliemeSiem
4

Ini akan menjadi komentar tetapi saya tidak bisa membuatnya sesuai dengan batasan:

Saya ingin menonaktifkannya hanya untuk impor Reference.cs dan WebService. Sebenarnya saya menggunakan makro untuk melakukannya untuk file. Cukup buka file dan jalankan makro ini (Diuji dalam VS2010):

Sub PragmaWarningDisableForOpenFile()
    DTE.ActiveDocument.Selection.StartOfDocument()
    DTE.ActiveDocument.Selection.NewLine()
    DTE.ActiveDocument.Selection.LineUp()
    DTE.ActiveDocument.Selection.Insert("#pragma warning disable 1591")
    DTE.ActiveDocument.Selection.EndOfDocument()
    DTE.ActiveDocument.Selection.NewLine()
    DTE.ActiveDocument.Selection.Insert("#pragma warning restore 1591")
    DTE.ActiveDocument.Save()
End Sub

Sebenarnya tidak ada cara untuk melakukan ini secara otomatis? Anda harus mengulang ini setiap kali kode yang dibuat secara otomatis menimpa file.

Kjellski
sumber
2
Saya pikir peringatan ini seharusnya tidak muncul untuk konten yang dibuat secara otomatis, mungkin Anda harus memeriksa pengaturan yang sesuai di properti proyek.
Gorgsenegger
1
Tidak, itu semua ditampilkan hanya dengan mengaktifkan peringatan XML-Comment. Dan tidak ada opsi untuk menonaktifkannya hanya untuk kode autogenerated. Karena itu terpotong ketika Anda membutuhkan regenerasi kode.
Kjellski
Di bawah properti proyek Code Analysis, ada opsi Supress results from generated code. Harus menjalankan kembali makro setelah setiap regenerasi kode sebenarnya bukan solusi IMO. Jika opsi di atas tidak bekerja untuk Anda, mungkin pembuat kode dapat disesuaikan untuk secara otomatis menambahkan pragma directive?
Laoujin
@Loujin terima kasih atas komentar Anda, tapi seperti yang saya sebutkan saya juga tidak suka solusi ini. Saya tidak dapat melihat alasan untuk downvote, saya telah menggunakan pengaturan yang Anda sebutkan tanpa keberhasilan. Adakah peluang Anda mencoba solusi Anda untuk impor WebService?
Kjellski