JSDoc Kullanarak JavaScript Kodu Nasıl Belgelenir

Uygun kod dokümantasyonu, yazılım geliştirmenin önemli ancak sıklıkla gözden kaçan bir yönüdür. Bir geliştirici olarak temiz, verimli kod yazmaya alışkın olacaksınız ancak iyi belgeler yazma konusunda daha az deneyimli olabilirsiniz.

İyi dokümantasyon, kodunuzla çalışan herkes için, ister ekibinizin diğer üyeleri olsun, ister siz, daha sonraki bir tarihte kendiniz olsun, faydalıdır. Bir şeyi neden belirli bir şekilde uyguladığınızı veya belirli bir işlevi veya API'yi nasıl kullanacağınızı açıklayabilir.

JavaScript geliştiricileri için JSDoc, kodunuzu belgelemeye başlamanın iyi bir yoludur.

JSDoc Nedir?

Kodu belgelemek karmaşık ve sıkıcı olabilir. Ancak, daha fazla insan bunun faydalarını kabul ediyor “kod olarak dokümanlar” yaklaşımıve birçok dilde sürecin otomatikleştirilmesine yardımcı olan kitaplıklar bulunur. Basit, açık ve özlü belgeler için. Tıpkı

JSDoc, JavaScript kaynak kodunuzdaki özel yorumları yorumlayarak, bu yorumları işleyerek ve özel belgeler üreterek belgeler oluşturur. Daha sonra bu dokümantasyonu erişilebilir bir HTML formatında kullanıma sunar.

Bu, belgeleri kodun içinde tutar; böylece kodunuzu güncellediğinizde belgeleri güncellemek kolaydır.

JSDoc'u Ayarlama

JSDoc'un yaratıcıları, JavaScript projenizde JSDoc'u başlatmayı ve kurmayı kolaylaştırdı.

JSDoc'u yerel olarak yüklemek için şunu çalıştırın:

npm install --save-dev jsdoc

Bu, kütüphaneyi projenize bir geliştirme bağımlılığı olarak yükleyecektir.

JSDoc'u kullanmak için kaynak kodunuzun içinde özel sözdizimi yorumlarını kullanacaksınız. Tüm dokümantasyon yorumlarınızı içine yazacaksınız. /** Ve */ işaretleyiciler. Bunların içinde tanımlı değişkenleri, fonksiyonları, fonksiyon parametrelerini ve daha fazlasını tanımlayabilirsiniz.

Örneğin:

/**
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */
functiongetUser(name) {
const User = name;
return User;
}

@param Ve @İadeler Etiketler, JSDoc'un kodunuzu açıklamak için desteklediği birçok özel anahtar kelimeden ikisidir.

Bu kodun belgelerini oluşturmak için şunu çalıştırın: npx jsdoc ardından JavaScript dosyanızın yolu.

Örneğin:

npx jsdoc src/main.js

jsdoc path/to/file.js

Bu komut bir oluşturacaktır dışarı proje kökünüzdeki klasör. Klasörün içinde belgelerinizin sayfalarını temsil eden HTML dosyalarını bulacaksınız.

Belgeleri şuradan görüntüleyebilirsiniz: barındırmak için yerel bir web sunucusu kurmaveya basitçe out/index.html dosyasını bir tarayıcıda açarak. Aşağıda bir dokümantasyon sayfasının varsayılan olarak nasıl görüneceğine ilişkin bir örnek verilmiştir:

JSDoc Çıkışını Yapılandırma

JSDoc'un varsayılan davranışını değiştirmek için bir yapılandırma dosyası oluşturabilirsiniz.

Bunu yapmak için bir conf.js dosyasını açın ve bu dosyanın içindeki bir JavaScript modülünü dışa aktarın.

Örneğin:

module.exports = {
 source: {
 includePattern: ".+\\\\.js(doc|x)?$",
 excludePattern: ["node_modules"],
 },
 recurseDepth: 5,
 sourceType: "module",
 opts: {
 template: "path/to/template",
 destination: "./docs/",
 recurse: true,
 },
};

Yapılandırma dosyasının içinde çeşitli JSDoc yapılandırması seçenekler. şablon seçeneği, belgelerin görünümünü özelleştirmek için bir şablon kullanmanıza olanak tanır. JSDoc topluluğu pek çok şey sağlar şablonlar kullanabileceğiniz. Paket ayrıca kendi kişiselleştirilmiş şablonlarınızı oluşturmanıza da olanak tanır.

Oluşturulan belgelerin konumunu değiştirmek için varış noktası Bir dizine yapılandırma seçeneği. Yukarıdaki örnekte bir dokümanlar projenin kökündeki klasör.

JSDoc'u bir yapılandırma dosyasıyla çalıştırmak için bu komutu kullanın:

jsdoc -c /path/to/conf.js

Bu komutu çalıştırmayı kolaylaştırmak için onu bir Kodlar içeri giriş paket.json dosya:

"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
 },

Şimdi yapabilirsin npm komut dosyası komutunu çalıştırın bir terminalin içinde.

JSDoc ile Oluşturulan Dokümantasyon Örneği

Aşağıda basit bir aritmetik kütüphanesi bulunmaktadır. eklemek Ve çıkarma yöntemler.

Bu, iyi belgelenmiş bir JavaScript kodu örneğidir:

/**
 * A library for performing basic arithmetic operations.
 * @module arithmetic
 */
module.exports = {
/**
 * Adds two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @return {number} The sum of the two numbers.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const sum = arithmetic.add(5, 10);
 * console.log(sum); // 15
 */
 add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a + b;
 },
/**
 * Subtracts the second number from the first number.
 * @param {number} a - The number to subtract from.
 * @param {number} b - The number to subtract.
 * @return {number} The result of the subtraction.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const difference = arithmetic.subtract(10, 5);
 * console.log(difference); // 5
 */
 subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a - b;
 }
//... other methods ...
};

JSDoc yorumları, aşağıdakiler de dahil olmak üzere kütüphanenin ve yöntemlerinin açık ve kapsamlı bir tanımını sağlar:

• Kütüphanenin tanımı ve amacı.
• Türleri ve kısa açıklamaları da dahil olmak üzere her yöntemin parametreleri.
• Her yöntemin döndürdüğü değer ve tür.
• Her yöntemin atabileceği hatalar ve buna sebep olan koşullar.
• Her yöntemin nasıl kullanılacağına dair bir örnek.

Yorumlarda ayrıca şunlar da yer alıyor: @modül Bu dosyanın bir modül olduğunu belirten etiket ve @örnek Her yöntem için bir kod örneği sağlamak üzere etiket.

Geliştirici Kodunu Doğru Şekilde Belgelemek

Gördüğünüz gibi JSDoc, JavaScript kodunu belgelemeye başlamanıza yardımcı olacak çok kullanışlı bir araçtır. Kolay entegrasyonu sayesinde kodunuzu yazarken hızlı ve ayrıntılı dokümantasyon oluşturabilirsiniz. Ayrıca belgeleri doğrudan çalışma alanınızda koruyabilir ve güncelleyebilirsiniz.

Bununla birlikte, JSDoc'un otomasyonu ne kadar yararlı olsa da, kaliteli belgeler oluşturabilmek için yine de belirli yönergelere uymanız gerekir.