C# veya VB dokümantasyon yorumlarında kalın veya italik mi?

Question

Kalın veya italic dokümantasyon yorumlarının kullanılması için bir yol var mı? Bir şey gibi:

/// <summary>Cleanup method. This is <b>recommended</b> way of cleanup.</summary> 
public void CleanAll(); 

List of predefined tags böyle bir özellik içermiyor, ancak/vurgu elde vurgulayarak bazı yol biliyor musunuz? Tercihen, kodun üzerine gelindiğinde araç ipuçlarında da gösterilebilseydi.

Orada <c> ve <code> var, ancak onlar zaten onların semantik var.

Answer 1

Kesinlikle değil, hayır. Ancak, Sandcastle (dokümantasyondan HTML üreten bir dokümantasyon oluşturucu) sadece HTML'yi kullanabilmeyi destekler, böylece Sandcastle ile oluşturursanız <em> ve <strong>'u kullanabilirsiniz.

Başka bir yolla belirtmek gerekirse: Jamiec zaten not ettiği gibi, XML dökümantasyon yorumları sadece XML'dir. Yani orada herhangi bir geçerli XML koyabilirsiniz; derleyici bu belgeyi XML dosyasına yazacaktır. Her şey bu dosyayı işleyen yazılıma bağlı. Sandcastle, HTML olarak bilmediği her şeyi aktarıyor, çünkü çıktı biçimi zaten bu.

yardım ipucu görüntülenirken Visual Studio sadece onları göz ardı eder:

: HTML etiketleri gösterir onun Ctrl + Q görünümde

ReSharper metin biraz çirkin şeyler yapar şekilde

Bunlar sadece sizin için Yine de başkaları tarafından kullanılmak üzere bir kütüphane yazar. Ama aynı zamanda IDE içinde 'un hiç kimsenin amacınıza uygun olmadığını görebilmeniz anlamına geliyor.

Aslında API belgelerini yazarken vurgulamaya çok az ihtiyaç duydum; çoğu zaman farklı bir cümle yazabilir veya son noktaya kadar ayrı bir paragrafta önemli düğümlere sahip olacak şekilde yeniden yapılandırabilirsiniz. Tutarlı dil ve kelime öbekleme, okuyucuların, kullanıldıklarında önemli notları almasına da yardımcı olur.

Kodunuz büyük olasılıkla bir örnekti, ancak özeti, yalnızca kısa bir cümlede - bir türün veya bir yöntemin ne kadar not aldığını gösterdiğinden bence en önemlisi. Eğer bir şey varsa, sözler içinde kullanın ve hatta o zaman gerçekten ihtiyacınız olup olmadığını dikkatlice düşünün.

Answer 2

Alternatif bir yöntem, bunun yerine bir wiki biçimlendirme benzeri stili kullanmaktır.

/// <summary>Cleanup method. This is *recommended* way of cleanup.</summary> 
public void CleanAll();