Derinlemesine Visual Studio Summary Kullanımı

Visual Studio ortamında uygulama geliştirirken metotların üzerine mouse ile gelip açılan bilgi kutucuğunda gördüğünüz içeriklerin bulunduğu bilgilendirici yorum bloklarına summary denir. 

XML yapıda olan bu açıklamalarda dokümantasyon işlemlerini kod tarafında halletmek isterseniz çok kullanışlıdır.

Visual Studio ortamında metodun üzerine gelip C# dili için üç adet slash /// girdiğinizde otomatik olarak aşağıdaki gibi yorum satırı gibi görünen summary kod yapısı oluşur. Aşağıdaki üç element, varsayılan olarak gelir. (parametreli metotlarda)


<summary> elementi metot hakkında temel açıklama yazmak,  

<param> elementi, varsa metodun aldığı her bir parametreyi açıklamak

<returns> elementi, varsa metodun dönüş değeri ile ilgili bilgilendirici yorum burada yazılır.

Parametre yazarken ve metodun üzerine gelince ortaya çıkan baloncuklar aşağıdaki görselde yer alıyor. Örnek metodu, parametrelerini ve ne döndürdüğünü tanımladık. 


Genel olarak bütün geliştiricilerin aşina olduğu bu kısmı anlattıktan sonra, muhtemelen nadiren karşılaştığınız elementlere değinip örnek kullanım paylaşacağım. Büyük projelerde veya hazır kütüphanelerdeki metotların üzerine geldiğinizde daha detaylı bilgiler olduğunu görürsünüz. Bahsedeceğim diğer elementler kullanılmıştır.

Örneğin LINQ - Where metodunun üzerine geldiğinizde tıklanabilen bölümler olduğunu görebilirsiniz. 


Bu metodun, summary versiyonu aşağıdaki gibidir. 


Kullanılabilecek elementlerin işlevlerini açıklamaya gelirsek;

<exception> : Metodumuzda karşılaşabileceğimiz hataya ait sınıfı veya fırlatacağımız exception tipini belirtmek istediğimizde kullanabiliriz. cref attributesine hata sınıfı tanımlanır. cref özelliğine alınabilecek hataya ait exception sınıfı yazılır. Elemente bilgilendirici yorum da yazabiliriz. Baloncukta Exceptions altına gelecektir.

<exception cref="ArgumentNullException">Bilgilendirici yorum</exception>


Aşağıdaki görsele View - Object Browser altında ulaşabilirsiniz, göreceğiniz gibi <exception> elementine yazdığımız açıklamayı görebiliriz. 

<paramref>: Metotta kullanılan parametre varsa, <summary> elementinde yazdığımız açıklamada parametreyi vurgulamak istediğimizde kullanabiliriz. name özelliğine parametrenin ismini vermeliyiz. 

<paramref name="name"/>

<param>: Visual Studio'da summary oluştururken eğer varsa her bir parametre hakkında bilgilendirici yazabilmek için ortaya çıkan elementtir. description olan alana metodu çağırıp parametre yazarken görünecek, ne işe yaradığını yazabiliriz. name özelliğine ise ilgili parametrenin adı yazılır, metot imzasında belirtilen isimle aynı olmasına dikkat edilir. 

<param name="name">description</param>

<value>: Bu element metotların aksine propertylerde summary oluşturulduktan sonra eklenebilir. Element içerisine propertyin değerini yorum olarak belirtebiliriz.


<example>: Metot için summary oluştururken, çağrılan sınıf kütüphanelerinde nasıl kullanabileceğimizi belirten örnekler yazmak istersek kullanabiliriz. Sık görülen kullanım örneği ise <code> elementi ile kullanılmasıdır.

<code>: Bu element arasında örnek kod parçası ekleyebiliriz. Summary baloncuğunda farklı bir fontta (HTML'deki code elementine yakın) görünür. Birden fazla satırlık kod parçasını summary baloncuğunda göstermek istersek kullanırız.

<example> Örnek kullanım aşağıdaki gibidir. 
<code> 
string name="Mert"; 
Greetings(name); 
</code>
</example>/


Summary tarafında bold (kalın) <b>, italic(sağa yatık) <i>, altı çizili <u>, code <c> gibi stiller verebiliriz. 

<c> elementi, HTML'deki code elementine karşılık geliyor. bir önceki <code> elementinden farklı olarak, tek satırlık kod yazılmak için kullanılabilir. Aşağıdaki görsellerde bu elementleri kullanıp, çıktısını görebilirsiniz. 


<remarks>: Summary yazarken, ekstra bilgi eklemek amacıyla kullanılan elementtir. Eğer uzun bilgi vermek gerekirse bu element işimizi görecektir. Yeni bir satırdan başlayarak özet bilgiye devam edilir. <remarks>'ta eklenen bilgiyi Object Explorer penceresinden ilgili metoda tıklanarak Remarks bölümünden de ulaşılabilir. 

<remarks>description</remarks>

Projemizde aşağıdaki gibi generic bir yapı kullanıyorsak, kullanabileceğimiz önemli iki element mevcuttur.


<typeparamref>: Generic yapıdaki T'yi summary blokları içerisinde referans olarak belirtebiliriz. name özelliğinde generic yapıyı belirten T tipinin adını verebiliriz. Yukarıdaki görsel için isim T'dir.

<typeparamref name="T"/>

<typeparam>: Generic yapıdaki T hakkında bilgilendirici içeriği yazabiliriz. 

<typeparam name="T">T için açıklama</typeparam>


Yukarıdaki görselde oluşan baloncukta, T: ile başlayan kısım <typeparam> elementinden geliyor. Summary'de <typeparamref> elementinde belirttiğimiz T tipi, sarı renkle vurgulanmaktadır.

T için Product sınıfını geçtikten sonra açıklamamız aşağıdaki gibi değişiyor. T'yi dinamik olarak düşünebilirsiniz. <typeparamref> 'in özelliği olduğunu görüyoruz.


<list>: Summary yorumlarında liste olarak görünecek bilgilendirici içerik eklenebilir. type özelliğine vereceğimiz noktalı (bullet) , numaralı (number) ve tablo(table) değerlerle değişik görünümde listeler oluşturabiliriz. 

list elementi içerisinde <listheader> kullanılırsa listenin başlığı mantığında çalışır. Listenin her bir elemanında <item> tagı bulunur, içerisine <description> (her bir maddenin açıklaması) ve <term> (kullanılması isteğe bağlıdır, ilgili maddeye başlık yazmak istediğimizde kullanılır.) tagları kullanılır. 

Aşağıdaki görseldeki listeleme type bilgisi table olarak verilmiştir.


<para>: HTML'deki <p> elementi ile aynı işlemde olup summary ve remarks elementleri içerisinde yazıldığında paragraf oluşturma işlemi yapar.

<include>: Bu element ile summary yorumlarını kod tarafında yazmayıp, ayrı bir XML dosyasından getiririz. Summary getirebilmek için bu elementte aşağıdaki özelliklere değerleri atamalıyız. 

<include file='filename' path='tagpath[@name="id"]' />

file: Summary yorumlarının bulunduğu XML dosyasının bulunduğu yolu ve adını veririz.
tagpath: Metoda ait summary bloğunun XML dosyasında bulunduğu element yoludur.
name: Summary yorumlarından önce id değerini vereceğimiz özelliktir. Her bir metot için ayrı olacaktır.
id: Sıklıkla kullanılacak metodun adını veririz.  

İlk görselde include elementinin kullanımını görüyoruz. file özelliğine dosyamızın yolunu verdik.
path özelliğinde ise Docs/Members xpath üzerinde, name değerine id olarak metodumuzun adını verdik. Böylece id değeri ile XML dosyasında o id'ye karşılık gelen yorumları alabiliriz.


Aşağıdaki görselde ise örnek bir XML kodunu görebilirsiniz. Members elementindeki ilgili id'deki summary bloklarının baloncuğa yansıdığını görüyoruz.


XML dosyası kullanmadan summary, param ve returns alanlarını metodun üzerine alırsak yine çalışacaktır.

<see>: Bu element, yorum içerisinde doğrudan kullanılabilen ve kod veya web sitesini referans verebilmemizi sağlar.

<see cref="member"/>

<see href="link">Link Text</see>

<seealso>: <see> elementi ile benzer işlemi yapmasına rağmen, yazılan yorum, Object Browser - See Also kısmında görünür

<seealso cref="member"/>

<seealso href="link">Link Text</seealso>

Her iki elementte de ortak bulunan özelliklere değinirsek;

cref: code reference anlamına gelmekte olup bir tipi veya metodu referans verebiliriz.

href: hyperlink reference anlamına gelmekte olup, web sitesini referans verebiliriz. 

Not: See Also özelliğine Visual Studio 2022'de rastlamadım, araştırmalarımda 2010 versiyonuna göre anlatılmış. - İlgili kaynak

Microsoft dokümanında da seealso elementini summary'de kullanamayacağımız belirtilmesine rağmen aşağıdaki örneğimde kullanabildiğimi gördüm. - İlgili kaynak

Şu durumda yorum içerisinde tıklanabilir bir referans vermek istersek her ikisi de kullanılabilir. 


Özetle summary blokları; metot, property gibi kod varlıkları hakkında dokümantasyon amaçlı XML tabanlı bilgilendirici yorumlardır. Bu yazıda summary yapısına derinlemesine inerek kullanılabilecek diğer elementlerden bahsettim. Yazıda bahsettiğim elementleri aşağıdaki gruplarda toplayabiliriz. 

Genel elementler
summary, remarks

Metot ve propertylerde kullanılan elementler
returns, param, paramref, exception, value

Stil elementleri
para, list, b, i ,u, c, code, example

Yeniden kullanılabilir, reuse mantığında çalışacak element
include

Referans gösterilmeyi sağlayan elementler
see, seealso

Generic yapılarda kullanılabilecek elementler
typeparam, typeparamref

Yorumlar

Yorum Gönder