Visual Studio üzerinde geliştirme yapan programcılar, yazdıkları kodların ne işe yaradığını hatırlamak maksadıyla methodlar üzerinde açıklama satırları bırakırlar.
 

Bu satırların açıklama maksatlı olduğunu belirtmek için dilden dile farklı işaretler kullanılmaktadır. Emsâl olarak C# içinde kullanılan // ve VB içinde kullanılan ise ' işaretleri gösterilebilir.
 

JavaScript üzerinde de yine aynı şekilde açıklama satırları oluşturmayı sağlayan belli karakterler mevcuttur. Bu yazıda bu karakterleri, standart açıklama satırlarını ve bilhassa da XML açıklama (documentation) için gerekli olan satırları, kısaca anlatmaya çalışacağım.

JavaScript kodlama da kullanılan açıklama/yorum satırları C# ile çok benzerlik göstermektedir. Ancak bazı noktalarda farklılıklar ihtiva etmektedir.
 

Mesela, kod bloğu içerisinde herhangi bir yerde tek satırlık bir açıklama koyacaksak aşağıdaki kullanım yeterlidir:
 

// Açıklama Satırı

Ancak maksadımız birden fazla satırdan oluşan açıklamalar eklemek ise, ekleyeceğiniz satırlar şöyle olmalıdır:

/*
 Açıklama satırı 1
 Açıklama satırı 2
 Açıklama satırı 3
*/

Şu ana kadar ki açıklama satırları, C# ve JavaScript kodlama da tamamen aynıdır, ancak bu satırlar temel olarak kod dosyasının içine baktığınız zaman size bilgi sunabilirler.
 

Eğer görmek istediğiniz; herhangi bir function'ı kullanmak istediğinizde karşınıza çıkması gereken açıklama satırları ise; bahsi geçen açıklama satırlarından istediğinizi, doğrudan function'ın başladığı satırın üzerine ekleyerek şu iki yolla da kullanabilirsiniz:

// Açıklama Satırı
function add(){}

2. Yol:

/*
   Açıklama Satırı 1
   Açıklama Satırı 2
   Açıklama Satırı 3
*/
function add(){}

Bu şekilde kullanımlara rağmen XML açıklamaları için uygun olan kullanım şekli bunlar değildir. Üstelik bu kullanım şekilleri ile parametreleri ve açıklamalarını, ilgili parametrenin yazımı sırasında görmek yerine doğrudan function adını yazdığınız sırada görürsünüz.
 

Bu sebeplerledir ki function'lar için gerekli açıklama satırlarını aşağıdaki şekillerde yazmak gereklidir.

function Get(str) {
    /// <summary>Function'a ait açıklamalar</summary>
    /// <param name="str" type="String">Bir String Değer</param>
    /// <returns type="String" />
    return str;
}

Buradaki kullanım şeklinde <summary></summary> arasına yazılan ifade function'ın ne iş yaptığını belirtir. <param></param> arasına yazılanlar ise her bir parametre hakkında bilgi içerir. <param> içerisine yazılan name ifadesi, açıklama satırının hangi parametreye ait olduğunu belirtmek için kullanılır ve yazılması mecburidir. Aksi durumda parametreye ait açıklama gösterilmeyecektir. type ifadesi ise gönderilen parametrenin tipini belirtmek için kullanılır ancak kullanılması mecburi değildir. Ayrıca içerisine yazılan ifade de yalnızca hatırlatma maksadı taşır. Bu sebeple standart değişken tipleri yerine herhangi bir kelime yazabilir, hatta birden fazla kelimeyi aralarında boşluk bırakarak bile ekleyebilirsiniz. Son olarak <returns /> satırı ile dönecek olan bilgi hakkında açıklama ekleyebilirsiniz ancak bu satırda mecburi değildir.

XML açıklamaları için eklenebilecek olan daha da güzel diğer bir kullanım şekli ise şöyledir:

function Get(a, c) {
    /// <signature>
    /// <summary>Birinci overload function açıklama satırı</summary>
    /// <param name="b" type="Number">Bir rakam.</param>
    /// <returns type="Number" />
    /// </signature>
    /// <signature>
    /// <summary>İkinci overload function açıklama satırı</summary>
    /// <param name="a" type="String">Bir string.</param>
    /// <returns type="Number" />
    /// </signature>
    return a;
}

Buradaki açıklama satırları bazı farklar dışında bir önceki ile hemen hemen aynıdır. Temel fark şu ki <signature></signature> ifadeleri, bu function'ın overload edildiğini (aşırı yüklendiğini) ifade etmek için kullanılmaktadır. Ancak dikkat etmek gereken bir nokta var ki buradaki overload ifadesi Visual Studio dillerinde olduğu gibi aynı isimde birden fazla method tanımlama şeklinde değildir. Buradaki husus bunun dışında olduğu için, bu mevzuyu es geçiyorum. Dileyenler 'JavaScript Function Overload' ifadesi ile arama yaparak gerekli bilgiye ulaşabilirler.

Tekrar mevzuumuza dönecek olursak; her <signature></signature> arasına yazılan ifade(ler) ayrı overload işlemlerine ait açıklamaları içerir(ler). Bir önceki kullanım şeklinden farklı olarak burada parametre ismini doğru yazmak mecburi değildir. Dilerseniz farklı isimler ile parametreleri gösterebilirsiniz. Misal olarak buradaki ilk <signature> içinde yer alan parametrenin name ifadesinde b yazmaktadır. Ancak bu kullanımda açıklamalar ile parametrelerlerin eşleştirilmesi yerine doğrudan <signature> içinde yazan ifadeler doğru kabul edildiğinden açıklama satırları görüntülenecektir. Hatta function parametre almasa, başka isimlerde parametre alsa ya da belirtilenden fazla parametre bile alsa, <signature> içinde belirtilen parametrelerle ilgili açıklamalar görüntülenecek ve gerçek parametreler burada gösterilmeyecektir. Bu duruma bağlı olarak parametre sıralamasının da bir ehemmiyeti kalmayacaktır. Ancak bu kullanım hataya düşmeye sebep olabileceği için pek doğru bir kullanım olarak gözükmemektedir.

Bu husus hakkında daha fazla bilgi edinmek isteyenler How to: Create JavaScript XML Documentation Comments başlıklı yazıyı inceleyebilirler.

Bu husus hakkında yazacaklarım şimdilik bu kadar :) Tekrar görüşünceye kadar, esen kalın, şen kalın ya da nasıl istiyorsanız öyle kalın :)