Şafak Ünel (Matematik Mühendisi)

Kodlarımızda kullanıdığımız metodları,parametreleri vb.. açıklamak için C#'ta otomatik olarak xml dökümantasyonu oluşturabiliriz.Ayrıca bu oluşturulan xml dosya compenentlerin IntelliSense'ini otomatik oluşturur. Bu yönden de bize artısı vardır. Bunu nasıl yapacağınızı ileri ki yazılarımızda sizle paylaşacağım şimdi C#'ta nasıl XML Comment Dökümanı Oluşturma oluşturulur ona bakalım.


Öncelikle Projemize sağ tıklayıp Properties tabına tıklayalım :



Properties'e tıkladığınızda aşağıdaki Properties ekranı açılacak. Bu ekrandaki "Xml dokumantation file" ı tıklayıp yanindaki textbox'a dökümanın yaratılmasını istediğimiz path'i yazarsak projemiz build edildiğinde bu lokasyona döküman yaratılacaktır.



Dosyanın nasıl otomatik oluşturulacağını öğrendik peki bu dosyaya nasıl oluşturduğumuz metodların, parametrelerin vb. commentlerini yollayacağız. Bunun için C#'ta metoddan önce "///" konulur.

summary : Kısa açıklama için kullanılır
remarks : Eğer açıklama daha uzunsa summary yerine remarks kullanılır
example : Örneğin bir metodun veya propety'in nasıl kullanıldığının örneğinin yazıldığı yer.
value : Property'in açıklamasının yapıldığı yer.
returns : Dönen değerin açıklamasının yapıldığı yer.
seealso : Mesela WriteLine metodunu kullanıysak bu metodun namespace'ini referans göstermek istiyorsak kullanılır.
param name="parametreAdi" : Örneğin bir metod "parametreAdi" isminde bir parametre alıyorsa bu parametrenin nereden geldiği gibi türü nedir gibi açıklamaların yapıldığı yer.

Kod içinde bunu nasıl yazdığımıza bakarsak :


xmlDokumantasyonuDemo() ismiyle oluşturduğum metodun üstüne görüldüğü gibi açıklamalar yazdık. Şimdi de bunların oluşturduğumuz xml dökümanımızda nasıl göründüğüne bakarsak :


görüldüğü gibi metodumuzun üstüne ayzdığımız açıklmaları içeren xml dökümanımız oluşturulmuş oldu.

Yazımızın başında bu oluşturulan xml dosya compenentlerin IntelliSense'ini otomatik oluşturur demiştik şimdi metodumuz için IntelliSense oluşturuldu mu ona bakalım. intelliSenceDemo isminde bir metod yazıp bu metodun içinden xmlDokumantasyonuDemo metodumuzu çağırırsak bunu kolayca test edebiliriz.

Görüldüğü gibi biz birinci parametre değerimiz olan denemeParameter1 için param tagı içinde "Bu parametre deneme parametremiz 1" açıklaması yazmıştık bu metodu kullanırken bu IntelliSense olarak artık nerede kullanırsak kullanalım açıklayıcı bilgi olarak bize yardımcı olacaktır. Ayni şekilde xmlDokumantasyonuDemo yazısının üstüne mouse'umuzu getirisek "Bu xml dokümantasyon nasıl oluşturulur görmemiz için örnek bir metoddur" şeklinde xml dökümanımızdan gelen bir açıklama bize yardımcı olacaktır. Bir çok kişinin ayni anda yazdığı projelerde xml dökümantasyonu bu yüzden çok önemlidir.