C# Uygulamalarında XML Dokümantasyonu Kullanmak

C# ile Uygulama Geliştirirken Yorum Satırlarını Kullanmak yazımda başladığım konuya XML Dokümantasyonunu eklemem gerekir.

Geleneksel C-tarzı yorum satırlarına ilave olarak C# geliştirilen kodların Xml Dokümantasyonunu otomatik olarak çıkartabilmek için, güçlü yorum operatörlerine sahiptir.

Bu yorum operatörleri (///) ile başlayan satırlara yazılır.

Aşağıdaki listedeki operatörler, derleyici (compiler) tarafından tanınır ve desteklenir;

<c> Tek satırı C# kodu olarak işaretler. Örneğin: <c>string AdSoyad = “Engin Polat”;</c> <code> Birden çok satırı C# kodu olarak işaretler. <example> İlgili satırları “örnek kod” olarak işaretler. <exception> Exception sınıfını dokümante eder. (Derleyici(compiler) tarafından kontrol edilir) <include> Başka bir dokümantasyon dosyasından yorum ekler. (Derleyici(compiler) tarafından kontrol edilir) <list> Dokümantasyona liste ekler. <param> Method parametresini dokümante eder. (Derleyici(compiler) tarafından kontrol edilir) <paramref> Kelimenin parametre olduğunu işaretler. (Derleyici(compiler) tarafından kontrol edilir) <permission> Öğeye erişim belirleyicisini dokümante eder. (Derleyici(compiler) tarafından kontrol edilir) <remarks> Öğeye açıklama ekler. <returns> Method’un dönüş tipini dokümante eder. <see> Başka bir parametreye çapraz-referans ekler. (Derleyici(compiler) tarafından kontrol edilir) <seealso> Açıklamaya “buna da bakın” parçası ekler. (Derleyici(compiler) tarafından kontrol edilir) <summary> Öğenin kısa açıklamasını dokümante eder. <value> Özelliği (property) tanımlar.

Örnek olması açısından, aşağıdaki Matematik sınıfını dokümantasyonu ile birlikte yazıyorum;

//Matematik.cs namespace Engin.Polat { ///<summary> ///  Engin.Polat.Matematik sınıfı. ///  İki rakamın toplanmasına yaran ///  Topla method’unu içerir. ///</summary> public class Matematik { ///<summary> ///  İki rakamın toplanmasını sağlar. ///</summary> ///<example>Örnek olarak: Topla(3, 5);</example> ///<returns>Toplama işleminin sonucu (int)</returns> ///<param name=”x”>Toplama işleminin ilk rakamı</param> ///<param name=”y”>Toplama işleminin ikinci rakamı</param> public int Topla(int x, int y) { return x + y; } } }</pre>

Derleme sonucu oluşan Xml dokümanı aşağıdaki gibidir;

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>ConsoleApplication4</name>
    </assembly>
    <members>
        <member name="T:Engin.Polat.Matematik">
            <summary>
                Engin.Polat.Matematik sınıfı.
                İki rakamın toplanmasına yaran
                Topla method'unu içerir.
            </summary>
        </member>
        <member name="M:Engin.Polat.Matematik.Topla(System.Int32,System.Int32)">
            <summary>
                İki rakamın toplanmasını sağlar.
            </summary>
            <example>Örnek olarak: Topla(3, 5);</example>
            <returns>Toplama işleminin sonucu (int)</returns>
            <param name="z">Toplama işleminin ilk rakamı</param>
            <param name="y">Toplama işleminin ikinci rakamı</param>
        </member>
    </members>
</doc>


Dikkat ederseniz, derleyici (compiler) bizim için  ve  elementlerini eklemiştir. Her  element'i name özelliğine sahiptir ve değer olarak öğenin tam adını içerir.

Değerin ilk harfi özel bir anlam taşır;

**T :** *Type*
**F :** *Field*
**M :** *Member*

blog comments powered by Disqus

Engin Polat hakkında

Chief Architect, Microsoft RD, Microsoft MVP

Ada ve Ege'nin babası ;)

Kategoriler

İstatistik

Makale Adedi: 459

Creative Commons Lisansı