Kapsamlı JSDoc Notları ve İpuçları

Giriş

JSDoc, JavaScript kaynak kod dosyalarını notlamak için kullanılan bir işaretleme dilidir. Kodu ve API'sini belgelendirmek için bir yol sağlar. Bu cheatsheet, ana JSDoc etiketlerini ve kullanımlarını kapsar.

Temel Yapı

Temel bir JSDoc yorumu şu şekilde görünür:

/**
 * Bu bir JSDoc yorumudur
 */

Fonksiyon Belgelendirme

/**
 * İki sayının toplamını hesaplar
 * @param {number} a - İlk sayı
 * @param {number} b - İkinci sayı
 * @returns {number} a ve b'nin toplamı
 */
function sum(a, b) {
    return a + b;
}

Sınıf Belgelendirme

/**
 * Bir kitabı temsil eder
 * @class
 */
class Book {
    /**
     * Bir kitap oluşturur
     * @param {string} title - Kitabın başlığı
     * @param {string} author - Kitabın yazarı
     */
    constructor(title, author) {
        this.title = title;
        this.author = author;
    }

    /**
     * Kitabın başlığını alır
     * @returns {string} Kitabın başlığı
     */
    getTitle() {
        return this.title;
    }
}

Yaygın Etiketler

@param

Bir fonksiyon parametresini tanımlamak için kullanılır.

/**
 * @param {string} name - Kişinin adı
 * @param {number} [age] - Kişinin yaşı (isteğe bağlı)
 * @param {boolean} [isStudent=false] - Kişinin öğrenci olup olmadığı (varsayılan: false)
 */
function describePerson(name, age, isStudent) {
    // Fonksiyon gövdesi
}

@returns

Bir fonksiyonun döndürdüğü değeri açıklar.

/**
 * @returns {Promise<string>} Bir selamlaşma ile çözümlenen bir promise
 */
async function getGreeting() {
    return "Merhaba, Dünya!";
}

@throws

Fırlatılabilecek istisnaları belgeler.

/**
 * @throws {Error} Girdi bir sayı değilse
 */
function squareRoot(x) {
    if (typeof x !== 'number') {
        throw new Error('Girdi bir sayı olmalıdır');
    }
    return Math.sqrt(x);
}

@type

Bir değişkenin veya özelliğin türünü belirtir.

/** @type {string} */
let name = "John Doe";

/** @type {number[]} */
let scores = [98, 85, 91];

@typedef

Özel bir tür tanımlar.

/**
 * @typedef {Object} Person
 * @property {string} name - Kişinin adı
 * @property {number} age - Kişinin yaşı
 */

/** @type {Person} */
let person = { name: "John", age: 30 };

@callback

Bir callback fonksiyonunu belgeler.

/**
 * @callback CompareCallback
 * @param {*} a - Karşılaştırılacak ilk öğe
 * @param {*} b - Karşılaştırılacak ikinci öğe
 * @returns {number} a < b ise negatif, a > b ise pozitif, eşitse sıfır
 */

/**
 * Bir karşılaştırma fonksiyonu kullanarak bir diziyi sıralar
 * @param {Array} arr - Sıralanacak dizi
 * @param {CompareCallback} compareFunc - Karşılaştırma fonksiyonu
 * @returns {Array} Sıralanmış dizi
 */
function customSort(arr, compareFunc) {
    return arr.sort(compareFunc);
}

@async

Bir fonksiyonun asenkron olduğunu belirtir.

/**
 * @async
 * @returns {Promise<string>} Veri ile çözümlenen bir promise
 */
async function fetchData() {
    // Fonksiyon gövdesi
}

@deprecated

Bir fonksiyonu veya metodu kullanım dışı olarak işaretler.

/**
 * @deprecated sürüm 2.0.0'dan itibaren, yerine yeniFonksiyon() kullanın
 */
function oldFunction() {
    // Fonksiyon gövdesi
}

@private, @protected, @public

Bir üyenin görünürlüğünü belirtir.

class MyClass {
    /**
     * @private
     */
    #privateMethod() {
        // Metod gövdesi
    }

    /**
     * @protected
     */
    _protectedMethod() {
        // Metod gövdesi
    }

    /**
     * @public
     */
    publicMethod() {
        // Metod gövdesi
    }
}

@example

Bir fonksiyon veya sınıfın nasıl kullanılacağına dair örnek sağlar.

/**
 * İki sayıyı toplar
 * @param {number} a - İlk sayı
 * @param {number} b - İkinci sayı
 * @returns {number} a ve b'nin toplamı
 * @example
 * // 5 döndürür
 * add(2, 3)
 */
function add(a, b) {
    return a + b;
}

@see

Başka bir sembole veya kaynağa atıfta bulunur.

/**
 * İlgili işlevsellik için {@link otherFunction} bakınız
 */
function someFunction() {
    // Fonksiyon gövdesi
}

@todo

Tamamlanması gereken görevleri belirtir.

/**
 * @todo Hata yönetimini uygulayın
 * @todo Negatif sayıları destekleyin
 */
function calculateSquareRoot(x) {
    return Math.sqrt(x);
}

@since

Bir fonksiyon veya özelliğin ne zaman eklendiğini belirtir.

/**
 * @since 1.5.0
 */
function newFeature() {
    // Fonksiyon gövdesi
}

@ignore

JSDoc'un belgelendirme oluştururken takip eden kodu göz ardı etmesini söyler.

/**
 * @ignore
 */
function internalHelper() {
    // Fonksiyon gövdesi
}