Bagaimana cara saya menghindar dari karakter dalam komentar c #?

112

Saya menyadari hari ini bahwa saya tidak tahu bagaimana cara melarikan diri dari karakter dalam komentar untuk C #. Saya ingin mendokumentasikan kelas C # generik, tetapi saya tidak dapat menulis contoh yang tepat karena saya tidak tahu cara keluar dari karakter <dan >. Apakah saya harus menggunakan <dan >? Saya tidak suka jika demikian karena saya ingin memudahkan untuk membaca komentar di dokumen yang sebenarnya jadi saya tidak perlu membuat semacam dokumen kode untuk dapat membaca kode contoh.

c#

— Tomas Jansson
sumber

1

Bisakah Anda menunjukkan contoh komentar?

— BoltClock

kemungkinan duplikat string Xml dalam komentar ringkasan C #

— Mark Pim

1

@ Mark: Anda benar, tapi ini bukan hanya XML ... Saya mencoba menulis contoh untuk obat generik yang bukan XML tetapi menggunakan '<' dan '>'. Tetapi solusinya sama untuk keduanya.

— Tomas Jansson

Mengingat popularitas template di C ++, Java, C # ... alasan apa yang mungkin dimiliki Microsoft untuk menggunakan pembatas XML setengah matang? Kurangnya kejelasan dan pandangan ke depan.

— Rick O'Shea

141

Jika Anda perlu meng-escape karakter dalam komentar XML, Anda perlu menggunakan entitas karakter, jadi <perlu di-escape sebagai <, seperti dalam pertanyaan Anda.

Alternatif untuk meloloskan diri adalah menggunakan CDATAbagian, untuk efek yang sama.

Seperti yang Anda catat, ini akan menghasilkan dokumentasi yang terlihat bagus, tetapi komentar yang mengerikan untuk dibaca ...

— Oded
sumber

19

Hanya untuk referensi <akan <dan >akan >. Sebagai contoh,List<string> myStringList = new List<string>();

— Arvo Bowen

@ArvoBowen Untuk berjaga-jaga jika seseorang melewatkan yang sudah jelas, lt/ gtsingkatan dari "kurang dari" / "lebih besar dari", masing-masing.

— Lukas Juhrich

1

Menariknya, hanya <perlu mendapatkan melarikan diri dengan <, >bisa tetap seperti itu: List<string> myStringList = new List<string>();. Setidaknya ini berhasil dalam intellisense. Anehnya, CDATA tidak bekerja dalam akal sehat. Saya tidak memeriksa tampilannya di dokumen yang dibuat secara otomatis.

— Peter Huber

Dapat mengonfirmasi bahwa VS 2013 tidak dirender CDATAdalam intellisense. <membuat komentar sulit dibaca.

— Alex

52

Dalam komentar C # biasa Anda dapat menggunakan karakter apa saja (kecuali */jika Anda memulai komentar dengan /*, atau karakter baris baru jika Anda memulai komentar dengan //). Jika Anda menggunakan komentar XML maka Anda dapat menggunakan bagian CDATA untuk memasukkan karakter '<' dan '>'.

Lihat artikel blog MSDN ini untuk informasi lebih lanjut tentang komentar XML di C #.

Sebagai contoh

/// <summary>
/// Here is how to use the class: <![CDATA[ <test>Data</test> ]]>
/// </summary>

— Mark Pim
sumber

12

Anda mungkin benar jika Anda ingin membuat dokumen html yang terlihat bagus, tetapi saya lebih tertarik untuk mendapatkan tip intellisense di VS yang benar, dan untuk itu sepertinya saya harus menggunakan XML escape. Tapi +1 untuk alternatifnya.

— Tomas Jansson

2

Hmm, sampah mesin yang tidak terbaca dalam komentar saya hanya membantu jika kita meluangkan waktu untuk membangun file dokumen kita ketika sebagian besar kasus penggunaan yang sangat luas (apakah saya sebutkan?) Membaca komentar di sumber (lebih disukai antarmuka) .

— Rick O'Shea

19

Anda berkata "Saya ingin memudahkan membaca komentar di dokumen sebenarnya". Saya setuju.

Pengembang menghabiskan sebagian besar hidupnya dalam kode , bukan membaca dokumen yang dibuat secara otomatis. Itu bagus untuk pustaka pihak ketiga seperti pembuatan bagan, tetapi tidak untuk pengembangan internal tempat kami bekerja dengan semua kode. Saya agak terkejut bahwa MSFT belum menemukan solusi yang mendukung pengembang dengan lebih baik di sini. Kami memiliki wilayah yang memperluas / menciutkan kode secara dinamis ... mengapa kami tidak dapat memiliki tombol perenderan komentar di tempat (antara teks mentah dan komentar XML yang diproses atau antara teks mentah dan komentar HTML yang diproses) ?. Sepertinya saya harus memiliki beberapa kemampuan HTML dasar dalam metode / kelas komentar prolog saya (teks merah, miring, dll). Tentunya sebuah IDE dapat melakukan sedikit keajaiban pemrosesan HTML untuk menghidupkan komentar sebaris.

Solusi hack-of-a-solution saya: Saya mengubah '<' menjadi "{" dan '> "menjadi"} ". Tampaknya itu menutupi saya untuk contoh tipikal gaya komentar penggunaan, termasuk contoh spesifik Anda. Tidak sempurna, tetapi pragmatis mengingat masalah keterbacaan (dan masalah dengan pewarnaan komentar IDE yang terjadi saat menggunakan '<')

— Dave
sumber

5

"Hack of a solution" Anda tampaknya lebih tepat dari yang Anda pikirkan. Menurut ini , kurung kurawal pengenal kompiler sebagai kurung sudut dan mengikatnya dengan benar .

— RubberDuck

8

C # Komentar XML ditulis dalam XML, jadi Anda akan menggunakan pelolosan XML biasa.

Sebagai contoh...

<summary>Here is an escaped &lt;token&gt;</summary>

— Bob Black
sumber

5

Saya telah menemukan solusi yang layak huni untuk masalah ini hanya menyertakan dua contoh: satu versi yang sulit dibaca di komentar XML dengan karakter escape, dan versi lain yang dapat dibaca menggunakan konvensional // komentar .

Sederhana tetapi efektif.

— HolySamosa
sumber

0

Lebih baik daripada menggunakan {...} adalah menggunakan ≤ ... ≥ (tanda kurang dari atau sama dengan, tanda lebih besar atau sama dengan, U2264 dan U2265 di Unicode). Tampak seperti tanda kurung sudut yang digarisbawahi tapi tetap saja tanda kurung sudut! Dan hanya menambahkan beberapa byte ke file kode Anda.

— Mick Bruno
sumber

0

Lebih baik lagi coba U2280 dan U2281 - cukup salin dan tempel dari Daftar karakter Unicode (bagian operator matematika).

— Paul Coulson
sumber

Operator unicode baik-baik saja ketika digunakan untuk mewakili operator matematika yang sebenarnya, buruk jika digunakan dalam potongan kode yang kebetulan ada dalam komentar (misalnya List<int>). Pikirkan tentang misalnya menyalin-tempel potongan kode.

— Palec

dapatkah Anda memberikan contoh bagaimana menggunakan ini dalam komentar? memang tidak pernah menggunakan karakter unicode

— ClementWalter

1

Salin dan tempel karakter seperti yang dijelaskan di atas.

— Paul Coulson