Cara Mendokumentasikan Kode JavaScript Menggunakan JSDoc

Dokumentasi kode yang tepat merupakan aspek penting namun sering diabaikan dalam pengembangan perangkat lunak. Sebagai seorang pengembang, Anda akan terbiasa menulis kode yang bersih dan efisien, namun Anda mungkin kurang berpengalaman dalam menulis dokumentasi yang baik.

Dokumentasi yang baik berguna bagi siapa pun yang bekerja dengan kode Anda, baik itu anggota tim Anda yang lain, atau Anda sendiri, di kemudian hari. Ini dapat menjelaskan mengapa Anda menerapkan sesuatu dengan cara tertentu atau cara menggunakan fungsi atau API tertentu.

Untuk pengembang JavaScript, JSDoc adalah cara yang baik untuk mulai mendokumentasikan kode Anda.

Apa itu JSDoc?

Mendokumentasikan kode bisa jadi rumit dan membosankan. Namun, semakin banyak orang yang menyadari manfaatnya pendekatan “dokumen sebagai kode”., dan banyak bahasa memiliki perpustakaan yang membantu mengotomatiskan prosesnya. Untuk dokumentasi yang sederhana, jelas, dan ringkas. Sama seperti

JSDoc menghasilkan dokumentasi dengan menafsirkan komentar khusus dalam kode sumber JavaScript Anda, memproses komentar tersebut, dan membuat dokumentasi yang dipesan lebih dahulu. Itu kemudian membuat dokumentasi ini tersedia dalam format HTML yang dapat diakses.

Hal ini menjaga dokumentasi tetap berada di dalam kode, sehingga saat Anda memperbarui kode, dokumentasi akan mudah diperbarui.

Menyiapkan JSDoc

Pembuat JSDoc telah mempermudah untuk memulai dan menyiapkan JSDoc di proyek JavaScript Anda.

Untuk menginstal JSDoc secara lokal, jalankan:

npm install --save-dev jsdoc

Ini akan menginstal perpustakaan di proyek Anda sebagai ketergantungan dev.

Untuk menggunakan JSDoc, Anda akan menggunakan komentar sintaksis khusus di dalam kode sumber Anda. Anda akan menulis semua komentar dokumentasi Anda di dalamnya /** Dan */ penanda. Di dalamnya, Anda dapat menjelaskan variabel tertentu, fungsi, parameter fungsi, dan banyak lagi.

Misalnya:

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

Itu @param Dan @kembali tag adalah dua dari banyak kata kunci khusus yang didukung JSDoc untuk menjelaskan kode Anda.

Untuk menghasilkan dokumentasi untuk kode ini, jalankan npx jsdoc diikuti dengan jalur ke file JavaScript Anda.

Misalnya:

npx jsdoc src/main.js

jsdoc path/to/file.js

Perintah ini akan menghasilkan keluar folder di root proyek Anda. Di dalam folder tersebut, Anda akan menemukan file HTML yang mewakili halaman dokumentasi Anda.

Anda dapat melihat dokumentasinya dengan menyiapkan server web lokal untuk menampungnya, atau cukup dengan membuka file out/index.html di dalam browser. Berikut ini contoh tampilan halaman dokumentasi secara default:

Mengonfigurasi Keluaran JSDoc

Anda dapat membuat file konfigurasi untuk mengubah perilaku default JSDoc.

Untuk melakukannya, buatlah a conf.js file dan ekspor modul JavaScript di dalam file ini.

Misalnya:

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

Di dalam file konfigurasinya bermacam-macam Konfigurasi JSDoc pilihan. Itu templat opsi memungkinkan Anda menggunakan templat untuk menyesuaikan tampilan dokumentasi. Komunitas JSDoc menyediakan banyak hal templat yang dapat Anda gunakan. Paket ini juga memungkinkan Anda membuat templat pribadi Anda sendiri.

Untuk mengubah lokasi dokumentasi yang dihasilkan, atur tujuan opsi config ke direktori. Contoh di atas menentukan a dokumen folder di root proyek.

Gunakan perintah ini untuk menjalankan JSDoc dengan file konfigurasi:

jsdoc -c /path/to/conf.js

Untuk mempermudah menjalankan perintah ini, tambahkan sebagai a skrip masuk ke dalam milikmu paket.json mengajukan:

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

Sekarang kamu bisa jalankan perintah skrip npm di dalam terminal.

Contoh Dokumentasi yang Dihasilkan Dengan JSDoc

Di bawah ini adalah perpustakaan aritmatika sederhana dengan menambahkan Dan mengurangi metode.

Ini adalah contoh kode JavaScript yang terdokumentasi dengan baik:

/**
 * 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 ...
};

Komentar JSDoc memberikan gambaran yang jelas dan komprehensif tentang perpustakaan dan metodenya, termasuk:

• Deskripsi perpustakaan dan tujuannya.
• Parameter setiap metode, termasuk jenis dan penjelasan singkatnya.
• Nilai dan tipe yang dikembalikan setiap metode.
• Kesalahan yang dapat ditimbulkan oleh setiap metode dan kondisi yang menyebabkannya.
• Contoh cara menggunakan setiap metode.

Komentar tersebut juga mencakup @modul tag untuk menunjukkan bahwa file ini adalah modul dan @contoh tag untuk memberikan contoh kode untuk setiap metode.

Mendokumentasikan Kode Pengembang dengan Cara yang Benar

Seperti yang Anda lihat, JSDoc adalah alat yang sangat berguna untuk membantu Anda mulai mendokumentasikan kode JavaScript. Dengan integrasinya yang mudah, Anda dapat menghasilkan dokumentasi yang cepat dan terperinci saat Anda menulis kode. Anda juga dapat memelihara dan memperbarui dokumentasi langsung di ruang kerja Anda.

Namun, meskipun otomatisasi JSDoc bermanfaat, Anda tetap harus mematuhi pedoman tertentu sehingga Anda dapat membuat dokumentasi yang berkualitas.