[1] Gambar 1. Pengenalan JSDoc.

Dokumentasi dalam pengembangan perangkat lunak mengacu pada proses mencatat dan menjelaskan informasi terkait dengan perangkat lunak yang dibuat. Konsep dasar dokumentasi melibatkan penulisan dokumentasi yang jelas, komprehensif, dan terstruktur yang mencakup berbagai aspek perangkat lunak, seperti persyaratan, desain, implementasi, penggunaan, dan pemeliharaan.

Kepentingan dokumentasi dalam pengembangan perangkat lunak sangatlah signifikan. Berikut adalah beberapa alasan mengapa dokumentasi penting:

1.      Keterbacaan dan pemahaman

Dokumentasi yang baik memungkinkan pengembang dan anggota tim lainnya untuk memahami perangkat lunak dengan lebih baik.

2.      Kolaborasi dan transfer pengetahuan

Dokumentasi yang baik memfasilitasi kolaborasi antara anggota tim pengembangan.

3.      Memudahkan pemecahan masalah

Ketika masalah muncul dalam perangkat lunak, dokumentasi yang baik dapat membantu dalam mendiagnosis dan memperbaiki masalah tersebut

4.      Pelatihan dan onboarding

Dokumentasi yang baik sangat berharga dalam pelatihan pengembang baru atau anggota tim baru.

5.      Pemeliharaan dan pengembangan masa depan

Dokumentasi yang terperinci memudahkan pemeliharaan dan pengembangan perangkat lunak di masa depan.

 

JSDoc adalah alat atau utilitas yang digunakan untuk menghasilkan dokumentasi terstruktur pada kode JavaScript. Ini memungkinkan pengembang untuk membuat dokumentasi yang konsisten, mudah dibaca, dan mudah dimengerti tentang API (Application Programming Interface) yang mereka tulis.

 

Dengan menggunakan JSDoc, pengembang dapat menambahkan komentar dokumentasi langsung ke dalam kode mereka menggunakan sintaks yang ditentukan. Komentar-komentar ini kemudian dapat diproses oleh JSDoc untuk menghasilkan dokumentasi yang terformat dengan baik, termasuk informasi tentang modul, kelas, metode, parameter, dan lainnya.

 

Salah satu keuntungan utama JSDoc adalah kemampuannya untuk menghasilkan dokumentasi yang konsisten secara otomatis. Dengan menambahkan komentar JSDoc yang tepat di tempat yang sesuai dalam kode, pengembang dapat menghasilkan dokumentasi yang mudah dikelola dan selalu terbaru.

 

Tujuan dari JSDoc adalah untuk mendokumentasikan API aplikasi JavaScript atau pustaka kalian. Diasumsikan bahwa kalian ingin mendokumentasikan hal-hal seperti modul, namespace, kelas, metode, parameter metode, dan sebagainya.

 

Komentar JSDoc sebaiknya ditempatkan tepat sebelum kode yang didokumentasikan. Setiap komentar harus dimulai dengan urutan /** agar dikenali oleh parser JSDoc. Komentar yang dimulai dengan /*, /***, atau lebih dari 3 bintang akan diabaikan. Ini adalah fitur yang memungkinkan kalian untuk menekan pemrosesan blok komentar.

Gambar 2. Contoh dokumentasi dalam bentuk deskripsi.

Komentar JSDoc /** Ini adalah deskripsi dari fungsi foo. */ digunakan untuk mendokumentasikan fungsi foo() agar pengguna kode dapat memahami fungsinya dengan jelas.

 

 

Instalasi dan Konfigurasi JSDoc

1.      Instalasi JSDoc

Gambar 3. Instalasi JSDoc menggunakan npm.

Pada contoh di gambar 3, kita menginstal jsdoc kedalam development dependencies menggunakan perintah npm i save-dev jsdoc.

2.      Membuat file config JSDoc

Gambar 4. Membuat file jsdoc.json didalam folder config.

Pada program di gambar 4, kita membuat konfigurasi untuk JSDoc. Dalam konfigurasi tersebut, ada beberapa pengaturan yang didefinisikan. Pertama, properti source digunakan untuk menentukan source code yang akan didokumentasikan. Dalam contoh ini, direktori "src" diikutsertakan dengan pola ".js$" untuk mencakup semua file JavaScript. Direktori "node_modules" dan "docs" dikecualikan dari proses dokumentasi. Kemudian, plugin "markdown" ditambahkan untuk mengizinkan penggunaan sintaks Markdown dalam dokumentasi. Pada properti template, opsi cleverlinks dan monospaceLinks diatur untuk menghasilkan tautan yang cerdas dan menggunakan tampilan monospace. Terakhir, properti opts mengatur opsi tambahan, seperti pengulangan secara recurse melalui direktori, dan destinasi folder tempat hasil dokumentasi akan disimpan, yaitu "./docs/".

3.      Membuat folder src dan file index.js

Gambar 5. Membuat folder src dan file index.js

4.      Jalankan npm run doc

Gambar 6. Menjalankan perintah npm run doc.

Pada contoh di gambar 6, kita menjalankan perintah npm run doc untuk menjalankan skrip bernama "doc" dalam proyek "myapp-3". Script ini mengarah ke perintah "jsdoc -c ./config/jsdoc.json", yang berarti menjalankan JSDoc dengan menggunakan file konfigurasi "./config/jsdoc.jsoni yang didefinisikan dalam file tersebut dan menghasilkan dokumentasi berdasarkan pengaturan yang ada.

Gambar 7. Folder yang dihasilkan dari perintah npm run doc.

5.      Membuat dokumentasi

Gambar 8. Membuat tag @type pada JSDoc.

Pada program di gambar 8, kita menggunakan JSDoc untuk memberikan dokumentasi tentang tipe data dari beberapa variabel. Pertama, ada dokumentasi untuk variabel studentName yang diberi tipe data string. Kemudian, ada dokumentasi untuk variabel grades yang merupakan array angka. Terakhir, ada dokumentasi untuk variabel todo yang merupakan objek dengan properti id (dapat berupa tipe data number atau string) dan text (tipe data string). Dengan menggunakan JSDoc, kalian dapat memberikan informasi tentang tipe data yang diharapkan dari variabel-variabel tersebut, memudahkan dalam pemahaman dan penggunaan kode. Kemudian untuk melihat hasilnya kalian bisa memberikan perintah npm run doc dan buka file index.html nya di browser.

Gambar 9. Hasil dari dokumentasi JSDoc.

Gambar 10. Membuat tag @param dan @return.

Pada program di gambar 10, kita menggunakan JSDoc untuk memberikan dokumentasi tentang fungsi calculateTax. Fungsi ini memiliki dua parameter, yaitu amount yang merupakan jumlah total dan tax yang merupakan persentase pajak. JSDoc memberikan informasi tentang tipe data dari kedua parameter tersebut, yaitu number. Selain itu, JSDoc juga memberikan informasi tentang nilai return dari fungsi ini, yaitu sebuah string yang berisi jumlah total dengan simbol dollar. Dengan adanya dokumentasi ini, pengguna kode dapat dengan jelas memahami fungsi calculateTax dan tipe data yang diperlukan, serta nilai kembalian yang diharapkan. Untuk menjalankannya bisa menggunakan perintah npm run doc dan refresh browser kalian untuk melihat hasilnya.

Gambar 11. Generating docs.

Pada program di gambar 11, kita menggunakan JSDoc untuk mendefinisikan struktur data dari objek Student. Dengan menggunakan tag @typeof, objek Student didefinisikan sebagai tipe data yang merupakan objek. Kemudian, menggunakan tag @property, setiap properti dari objek Student dijelaskan. Properti id adalah tipe data number yang merepresentasikan ID mahasiswa, properti name adalah tipe data string yang merepresentasikan nama mahasiswa, properti age adalah tipe data string atau number yang merepresentasikan usia mahasiswa (opsional), dan properti isActive adalah tipe data boolean yang menunjukkan apakah mahasiswa tersebut aktif. Dengan adanya dokumentasi ini, pengguna kode dapat memahami struktur objek Student beserta tipe data yang harus diberikan pada setiap propertinya.

Gambar 12. Membuat class pada JSDoc.

Pada program di gambar 12, kita mendefinisikan class Person yang digunakan untuk membuat objek person. Dalam constructor class, parameter personInfo digunakan untuk menginisialisasi properti name dan age dari objek person. Properti name adalah tipe data string yang merepresentasikan nama person, sedangkan properti age adalah tipe data string yang merepresentasikan usia person. Selain itu, class Person juga memiliki metode greet yang digunakan untuk menampilkan pesan salam dengan menggunakan nama dan usia person. Dengan menggunakan JSDoc, dokumentasi ini memberikan informasi tentang struktur class Person, tipe data properti, dan tipe data kembalian metode greet.

Gambar 13. Membuat link pada JSDoc.

Pada program di gambar 13, kita membuat objek person1 menggunakan class Person. Objek ini memiliki properti name dengan nilai "Rizky Athoriq" dan properti age dengan nilai 22. Selain itu, komentar JSDoc pada baris pertama memberikan referensi ke class Person menggunakan tag {@link Person}. Dokumentasi ini menghubungkan objek person1 dengan definisi kelas Person yang sudah dijelaskan sebelumnya, sehingga memudahkan dalam melihat informasi lebih lanjut tentang kelas tersebut.

6.      Membuat Module

Untuk membuat modul kita perlu membuat file baru di dalam folder src, buat file bernama calculator.js yang akan diimport ke dalam file index.js

Gambar 14. Isi dari file calculator.js

Kemudian kita import calculator.js kedalam index.js menggunakan require atau bisa lihat di gambar 15.

Gambar 15. Mengimport modul calculator.

Pada program di gambar 15, kita menggunakan metode require untuk mengimpor modul "calculator" yang berisi empat fungsi: add, subtract, divide, dan multiply. Dengan menggunakan sintaksis destructuring assignment pada konstanta, kita dapat mengambil fungsi-fungsi tersebut secara langsung dan menggunakannya dalam kode berikutnya. Kemudian jalankan perintah npm run doc untuk melihat hasilnya.

Gambar 16. Hasil dari dokumentasi menggunakan JSDoc.

 

 

Quiz

1. Apa yang dimaksud dengan dokumentasi dalam pengembangan perangkat lunak?

a) Proses memperbaiki bug dalam perangkat lunak

b) Proses mencatat dan menjelaskan informasi terkait perangkat lunak

c) Proses menguji perangkat lunak sebelum dirilis

d) Proses mengumpulkan kebutuhan pengguna perangkat lunak

e) Proses mengembangkan desain perangkat lunak

2. Mengapa dokumentasi penting dalam pengembangan perangkat lunak?

a) Untuk membuat kode program lebih kompleks

b) Untuk menyembunyikan informasi dari pengguna

c) Untuk memudahkan pemecahan masalah

d) Untuk meningkatkan keamanan perangkat lunak

e) Untuk mengurangi waktu pengembangan perangkat lunak

3. Apa yang dimaksud dengan JSDoc?

a) Alat untuk menghasilkan dokumentasi terstruktur pada kode JavaScript

b) Bahasa pemrograman untuk mengembangkan perangkat lunak

c) Metode untuk menguji perangkat lunak

d) Standar format file JavaScript

e) Platform untuk mempublikasikan perangkat lunak

4. Apa tujuan dari JSDoc?

a) Mendokumentasikan API aplikasi JavaScript atau pustaka

b) Memperbaiki bug dalam kode JavaScript

c) Mengimplementasikan fitur baru dalam JavaScript

d) Mengurangi ukuran file JavaScript

e) Meningkatkan kecepatan eksekusi kode JavaScript

5. Bagaimana cara menginstal JSDoc?

a) Menggunakan perintah "npm install jsdoc"

b) Mengunduh dari situs web resmi JSDoc

c) Menggunakan perintah "npm run doc"

d) Menggunakan perintah "jsdoc -c ./config/jsdoc.json"

e) Menggunakan perintah "npm init" dan "npm install jsdoc --save-dev"

6. Di mana komentar JSDoc sebaiknya ditempatkan dalam kode?

a) Setelah kode yang didokumentasikan

b) Sebelum kode yang didokumentasikan

c) Di tengah kode yang didokumentasikan

d) Di luar blok komentar

e) Tidak ada aturan yang khusus

7. Apa yang dimaksud dengan tag @param dalam JSDoc?

a) Menentukan tipe data return dari fungsi

b) Menentukan tipe data parameter dalam fungsi

c) Menambahkan deskripsi fungsi

d) Menentukan nama fungsi

e) Menentukan nama parameter dalam fungsi

8. Apa yang dimaksud dengan tag @return dalam JSDoc?

a) Menentukan tipe data parameter dalam fungsi

b) Menambahkan deskripsi fungsi

c) Menentukan tipe data return dari fungsi

d) Menentukan nama fungsi

e) Menentukan nama parameter dalam fungsi

 

9. Bagaimana cara menghasilkan dokumentasi menggunakan JSDoc?

a) Menjalankan perintah "npm run doc"

b) Menjalankan perintah "jsdoc -c ./config/jsdoc.json"

c) Menulis manual dokumentasi menggunakan JSDoc sintaksis

d) Menggunakan perintah "npm install jsdoc"

e) Menggunakan JSDoc secara otomatis tanpa perlu perintah tambahan

10. Apa manfaat dari menggunakan JSDoc dalam pengembangan perangkat lunak?

a) Membuat kode program lebih kompleks

b) Mempercepat waktu pengembangan perangkat lunak

c) Memudahkan pemecahan masalah dalam perangkat lunak

d) Mengurangi ukuran file JavaScript

e) Menghilangkan kebutuhan untuk dokumentasi

 

Referensi

Use JSDoc: Index

(1) Documenting Your JavaScript | JSDoc Crash Course - YouTube