JSDoc ile dokümantasyon için örnek kod

giriiş

JSDoc JavaScript'te API dokümantasyonu oluşturmak için açık kaynaklı bir araçtır. Geliştiricilerin kodlarını yorumlar kullanarak belgelemelerine olanak tanır.

JSDoc ile dokümantasyon için örnek kod

Aşağıda bir yöntemin nasıl belgelendirileceğine dair bir örnek verilmiştir:

/**
* یک فایل را بر اساس شناسه بازیابی می‌کند.
* @param {string} id شناسه فایل.
* @returns {File} شی فایل.
*/
const getFileById = (id) => {
// کد...
}

JSDoc'u yükleyin

JSDoc'u kullanarak global olarak kullanabilirsiniz npm Düzenlemek:

npm install -g jsdoc

Veya belirli bir proje için aşağıdaki gibi kurulum yapabilirsiniz:

npm install --save-dev jsdoc

JSDoc nasıl kullanılır

Belgeleri ekle

Kodunuzu belgelemeye başlamak için, sadece şu ifadeyi içeren bir yorum ekleyin: /** Her kod bloğunun (modüller, metotlar, sınıflar, fonksiyonlar, vb.) en üstüne şunu ekleyin:

/**
* کاربر را با استفاده از ایمیل بازیابی می‌کند.
*/
const getByEmail = async (email) => {
// کد...
}

Daha fazla bilgi eklemek için JSDoc etiketlerini de kullanabilirsiniz:

/**
* کاربر را با استفاده از ایمیل بازیابی می‌کند.
* @async
* @method
* @param {String} email - ایمیل کاربر
* @returns {User} شی کاربر
* @throws {NotFoundError} اگر کاربر پیدا نشود.
*/
const getByEmail = async (email) => {
// کد...
}

Dokümantasyon üretimi

Yorumları ekledikten sonra dokümantasyonu web sitesi olarak oluşturmak için aşağıdaki komutu çalıştırmanız yeterlidir:

jsdoc path/to/my/file.js

Gelişmiş İpuçları

Yapılandırma dosyasını kullanma

Projeniz büyükse ve çok sayıda dosya ve klasör içeriyorsa, JSDoc'un davranışını özelleştirmek için bir yapılandırma dosyası kullanabilirsiniz:

{
"source": {
"includePattern": ".+\\.js(doc|x)?$", // فقط فایل‌های با پسوند .js، .jsdoc یا .jsx پردازش شوند.
"include": ["."], // تمام پوشه‌ها بررسی شوند.
"exclude": ["node_modules"] // پوشه node_modules نادیده گرفته شود.
},
"opts": {
"destination": "./docs/", // مقصد تولید مستندات.
"recurse": true // پوشه‌ها به صورت بازگشتی بررسی شوند.
}
}

VSCode'da Destek

VSCode editörü varsayılan olarak JSDoc'u destekler ve yorum yapılarının otomatik tamamlanması ve fonksiyon bilgilerinin görüntülenmesi gibi özellikler sunar.

Özel bir şablon kullanın

Varsayılan JSDoc biçimini bir dosya oluşturarak geçersiz kılabilirsiniz düzen.tmpl Yapılandırma dosyasında özelleştirin ve belirtin.

Sonuç

JSDoc, geliştiricilerin kodlarını daha iyi anlamalarına yardımcı olmanın yanı sıra otomatik API dokümantasyonu oluşturma özelliği de sağlayan güçlü bir JavaScript kod dokümantasyon aracıdır.