C # açıklamalarındaki karakterlerden nasıl kaçış yaparım?

112

Bugün C # için yorumlardaki karakterlerden nasıl kaçılacağımı bilmediğimi fark ettim. Genel bir C # sınıfını belgelemek istiyorum, ancak <ve >karakterlerinden nasıl kaçacağımı bilmediğim için uygun bir örnek yazamıyorum . Ben kullanmak zorunda mı <ve >? Asıl belgedeki yorumu okumayı kolaylaştırmak istediğim için durumun böyle olmasını sevmiyorum, böylece örnek kodu okuyabilmek için bir tür kod belgesi oluşturmam gerekmiyor.

c#

— Tomas Jansson
kaynak

1

Örnek bir yorum gösterebilir misiniz?

— BoltClock

C # özet yorumunda Xml dizesinin

— Mark Pim

1

@Mark: Haklısın, ama bu sadece XML değil ... XML olmayan ama '<' ve '>' kullanan jenerikler için bir örnek yazmaya çalışıyordum. Ancak çözüm her ikisi için de aynı.

— Tomas Jansson

Şablonların C ++, Java, C # ... içindeki popülerliği göz önüne alındığında, Microsoft yarı pişmiş XML sınırlayıcıları kullanmak için hangi olası bahaneye sahip? Her zamanki netlik ve öngörü eksikliği.

— Rick O'Shea

141

XML yorumlardaki karakterlerden kaçış yapmanız gerekiyorsa, karakter varlıklarını kullanmanız gerekir, bu nedenle sorunuzda olduğu gibi <kaçılmanız gerekir <.

Kaçışa alternatif CDATA, aynı etkiye sahip bölümleri kullanmaktır .

Sizin de belirttiğiniz gibi, bu iyi görünümlü belgeler üretecektir, ancak okunması korkunç bir yorum ...

— Oded
kaynak

19

Sadece referans için <olurdu <ve >olurdu >. Örnek olarak,List<string> myStringList = new List<string>();

— Arvo Bowen

@ArvoBowen Birinin bariz olanı kaçırması durumunda, lt/ gtsırasıyla "küçüktür" / "büyüktür" anlamına gelir.

— Lukas Juhrich

1

İlginçtir, sadece <birlikte kaçan almak gerekiyor <, >olduğu gibi kalabilir: List<string> myStringList = new List<string>();. En azından bu akıllıca çalışıyor. Garip bir şekilde, akıllıca CDATA çalışmıyor. Otomatik oluşturulan belgelerde nasıl göründüğünü kontrol etmedim.

— Peter Huber

VS 2013'ün CDATAintellisense'de işlenmediğini doğrulayabilir . <yorumun okunmasını zorlaştırır.

— Alex

52

Düz C # yorumlarında herhangi bir karakteri kullanabilirsiniz ( */yorumu ile başlatmanız veya yorumu ile başlattıysanız /*yeni satır karakteri dışında //). XML açıklamaları kullanıyorsanız , '<' ve '>' karakterlerini eklemek için bir CDATA bölümü kullanabilirsiniz .

C # 'daki XML yorumları hakkında daha fazla bilgi için bu MSDN blog makalesine bakın .

Örneğin

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

— Mark Pim
kaynak

12

Güzel görünümlü html belgeleri oluşturmak istiyorsanız muhtemelen haklısınızdır, ancak VS'deki intellisense ipuçlarını doğru bir şekilde almak konusunda daha ilginçim ve bunun için XML kaçışını kullanmam gerekiyor gibi görünüyor. Ancak alternatif için +1.

— Tomas Jansson

2

Hmm, yorumlarımdaki okunaksız makine çöpü, yalnızca belge dosyamızı oluşturmak için zaman ayırırsak yardımcı olur, kullanım durumlarının büyük çoğunluğu kaynaktaki yorumları (tercihen bir arayüz) okurken (çok mu bahsetmiştim?) .

— Rick O'Shea

19

"Asıl belgedeki yorumu okumayı kolaylaştırmak istiyorum" dediniz. Katılıyorum.

Geliştiriciler , otomatik olarak oluşturulan belgeleri inceleyerek değil, yaşamlarının çoğunu kodda geçirirler . Bunlar, çizelge oluşturma gibi üçüncü taraf kitaplıkları için harikadır, ancak tüm kodla çalıştığımız kurum içi geliştirme için harikadır. MSFT'nin burada geliştiricileri daha iyi destekleyen bir çözüm bulamadığı için şok oldum. Kodu dinamik olarak genişleten / daraltan bölgelerimiz var ... neden yerinde yorum oluşturma geçişine sahip olamıyoruz (ham metin ile işlenmiş XML yorumu arasında veya ham metin ile işlenmiş HTML yorumu arasında)? Yöntem / sınıf prolog yorumlarımda (kırmızı metin, italik, vb.) Bazı temel HTML yeteneklerim olmalı gibi görünüyor. Şüphesiz bir IDE, satır içi yorumları canlandırmak için biraz HTML işleme sihri yapabilir.

Çözüm hackleme çözümüm : '<' yerine "{" ve '> "' yi"} "olarak değiştiriyorum. Bu, sizin özel örneğiniz de dahil olmak üzere tipik örnek kullanım stili yorumunu kapsıyor gibi görünüyor. Kusursuz ama pragmatik okunabilirlik sorunu (ve '<' kullanıldığında ortaya çıkan IDE yorum renklendirmesiyle ilgili sorunlar) göz önüne alındığında

— Dave
kaynak

5

"Çözüm hack" iniz düşündüğünüzden daha doğru görünüyor. Buna göre , derleyici tanıyıcı, köşeli parantez olarak parantez içine alır ve bunları doğru bir şekilde bağlar .

— RubberDuck

8

C # XML yorumları XML'de yazılır, bu nedenle normal XML kaçışını kullanırsınız.

Örneğin...

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

— Bob Siyah
kaynak

5

Bu soruna yaşanabilir bir çözüm buldum basitçe iki örnek içeriyor: XML yorumlarda kaçış karakterli okunması zor bir sürüm ve geleneksel //yorumları kullanan başka bir okunabilir sürüm .

Basit ama etkili.

— HolySamosa
kaynak

0

{...} kullanmaktan daha iyi, ≤ ... ≥ kullanmaktır (işaretten küçük veya eşittir, işaretten büyük veya eşittir, Unicode'da U2264 ve U2265). Altı çizili açılı ayraçlara benziyor ama yine de kesinlikle açılı ayraçlar! Ve kod dosyanıza yalnızca birkaç bayt ekler.

— Mick Bruno
kaynak

0

Daha da iyisi U2280 ve U2281'i deneyin - sadece Unicode karakterleri Listesi'nden (matematiksel operatörler bölümü) kopyalayıp yapıştırın .

— Paul Coulson
kaynak

Unicode operatörleri, gerçek matematiksel operatörleri temsil etmek için kullanıldıklarında iyi durumda, bir yorumda bulunan kod parçacıklarında kullanılıyorsa zayıftır (örneğin List<int>). Örneğin, kod parçacığını kopyalayıp yapıştırmayı düşünün.

— Palec

bunu bir yorumda nasıl kullandığınıza dair bir örnek verebilir misiniz? Gerçekten de hiçbir zaman kullanılan Unicode karakterleri

— ClementWalter

1

Karakteri yukarıda açıklandığı gibi kopyalayıp yapıştırın.

— Paul Coulson