Advertisement
  1. Code
  2. Tools & Tips
Code

Mendokumentasikan JavaScript dengan YUIDoc

by
Difficulty:BeginnerLength:LongLanguages:

Indonesian (Bahasa Indonesia) translation by Muhammad Gufron (you can also view the original English article)

Mendokumentasikan kode Anda agak seperti pengujian; kita semua tahu kita harus melakukannya, kita tidak benar-benar yakin bagaimana, dan kebanyakan orang, jika kita jujur, sama sekali tidak, tetapi mereka yang melakukannya adalah pendukung besar dari itu. Tutorial ini akan membantu Anda sampai dengan kecepatan pada salah satu cara terbaik untuk mengatasi itu: YUIDoc.


Apa itu YUIDoc?

YUIDoc akan menghasilkan dokumentasi API didasarkan pada komentar yang Anda tulis.

YUIDoc adalah app NodeJS yang akan menghasilkan dokumentasi API (dalam bentuk HTML), didasarkan pada komentar yang Anda tulis dalam sourcecode JavaScript Anda. Sebenarnya, hal ini tidak hanya untuk JavaScript: bahasa pemrograman apapun yang mendukung blok komentar yang dibatasi oleh /* */ bekerja untuk YUIDoc. Seperti yang Anda duga, YUIDoc adalah salah satu alat yang Yahoo! terbitkan bersama dengan Library YUI mereka.

Untuk menginstal YUIDoc, Anda akan memerlukan NodeJS dan Node package manager (npm) yang diinstal terlebih dahulu. Kemudian, Anda dapat menginstal YUIDoc melalui npm -g install yuidocjs. Anda akan menggunakannya dengan menjalankan yuidoc <path to="" js="" folder="">; lain tentang ini nanti.</path>


Ini Semua Tentang Tag

Jadi, Anda tahu bahwa YUIDoc mendapatkan dokumentasi dari multiline komentar di source file. Tentu saja, Anda mungkin memiliki komentar yang bukan bagian dari dokumentasi. Agar YUIDoc mengenali komentar penting, komentar harus mulai dengan awal ganda: /**. Jadi:

Tentu saja, itu yang ada di dalam jumlah itu (di dalam blok komentar, itu dia). Masing-masing harus menyertakan satu dan hanya satu tag utama; Hal ini juga dapat mencakup tag sekunder nol atau lebih. Sungguh, YUIDoc sesederhana itu: tambahkan komentar dengan tag yang tepat untuk kode Anda, dan presto: dokumentasi! Jadi mari kita belajar beberapa tag. Berikut ini cara kami melakukan ini: kami akan membahas tag, dan di mana tag itu digunakan, dengan contoh sederhana penggunaannya; kemudian, kami akan menulis dan mendokumentasikan beberapa kode sehingga Anda memiliki gagasan yang lebih baik tentang cara kerja tag bersama-sama.


Tags Utama

Sebelum masuk ke tag utama, ingat bahwa setiap blok komentar hanya dapat memiliki satu tag utama. Ini menggambarkan apa yang diberikan potongan kode.

@module

Tag @module menjelaskan sekelompok kelas yang berhubungan. (Ya, ya, JavaScript tidak memiliki kelas: YUIDoc mengacu pada fungsi konstruktor.) Jika Anda menggunakan YUIDoc untuk mendokumentasikan BackboneJS, objek Backbone akan menjadi modul, karena menyimpan Model, Collection, View, dan kelas lainnya. Tepat setelah tag, Anda memasukkan nama modul.

@class

Tag @class tepat menggambarkan kelas tunggal Dalam Library YUI, ini biasanya berarti fungsi konstruktor, tetapi jika Anda memilih untuk menggunakan pola yang berbeda dan menyebutnya kelas Anda, Anda dapat melakukannya juga. Setiap komentar dengan tag @class juga harus memiliki tag @static atau @constructor (Tag sekunder yang akan kita bahas segera).

Jika kelas Anda adalah bagian dari modul, Anda tidak perlu melakukan apa-apa dalam komentar @class untuk menetapkan bahwa: Pastikan bahwa ada @module ada blok komentar di bagian atas dari file tersebut.

@method

Tentu saja, setiap kelas akan memiliki setidaknya beberapa methods, dan Anda akan menggunakan tag @method untuk mendeskripsikannya. Nama metode akan digunakan setelah tag, dan Anda akan menggunakan tag sekunder @return dan @params untuk mendiskripsikannya.

@property

Tag @property digunakan untuk menandai properti suatu class. Anda akan menggunakan tag sekunder @type dan @default dengan yang satu ini, pasti.

@event

Jika Anda memiliki acara kustom yang kelas dapat api, Anda akan ingin menggunakan tag @event untuk mendiskripsikannya. Berikut adalah apa yang YUIDoc dokumentasi dikatakan:

Sebuah blok @event ini agak mirip dengan blok @method, kecuali bahwa @return tidak relevan, dan @param digunakan untuk mendeskripsikan properti yang menggantung dari objek event yang dipanggil oleh callback untuk menerima event.


Tag Sekunder

Komentar blok dapat memiliki lebih dari satu tag sekunder; mereka akan sering memiliki beberapa, dan kadang-kadang bahkan lebih dari satu jenis yang sama. Mari kita lihat beberapa yang akan sering Anda gunakan.

@submodule

Jika Anda sedang membagi modul Anda ke submodul (mungkin submodule per file, mungkin tidak), tag @submodule akan melayani Anda.

@extends

Tag @extends ini berguna bila Anda memiliki hubungan superclass/subclass.  Anda dapat mengklaim class yang merupakan induk dari kelas yang saat ini didokumentasikan:

@constructor

Jika kelas dapat di instantiated, artinya dibutuhkan fungsi konstruktor. Jika Anda menggunakan pola prototipe standar dalam JavaScript, deklarasi kelas juga merupakan konstruktor. Itu berarti Anda akan sering melihat sesuatu seperti ini:

Bahkan, Anda mungkin ingat saya mengatakan bahwa setiap tag @class harus memiliki tag sekunder @constructor atau @static.

@static

Berbicara tentang @static, ini dia. Kelas dianggap statis ketika Anda tidak dapat membuat instance dari itu. Sebuah contoh yang baik ini adalah built-in Math objek: Anda tidak pernah membuat sebuah instance dari itu (new Math()), Anda memanggil methods dari kelas itu sendiri.

Sebuah metode juga dapat statis: jika kelas dapat instantiated, tetapi juga memiliki beberapa metode tingkat-kelas, metode ini dianggap statis (mereka disebut pada kelas, bukan contoh).

Dalam contoh ini, Anda dapat membuat sebuah instance Person, tetapi semua metode statis.

@final

Tag ini digunakan untuk properti atau atribut, dan menandai kata properti sebagai konstan: itu tidak dapat diubah. Sementara JavaScript tidak memiliki konstanta nyata dalam keadaan saat ini, pemandu pola atau gaya pengkodean mungkin menggunakannya pada prinsipnya, jadi ini akan berguna untuk itu.

@param

Berikut adalah bagian penting: Tag @param digunakan untuk mendefinisikan parameter dari @method (termasuk @constructor) atau @event. Ada tiga bits info yang digunakan setelah @param tag: nama parameter, jenis (yang ini opsional) dan deskripsi. Ini dapat berupa deskripsi tipe nama pesanan atau deskripsi nama jenis; tetapi dalam kedua kasus, tipe harus dikelilingi oleh kurung kurawal.

Ada beberapa cara untuk mengkustom bagian name juga. Menempatkannya dalam tanda kurung persegi menandainya sebagai opsional, sementara menempatkan =someVal setelah itu menunjukkan nilai defaultnya (jelas, hanya parameter opsional memiliki nilai default). Kemudian, jika itu adalah pengganti untuk lebih dari satu argumen, menambahkan * untuk menunjukkan bahwa. (Jelas, name* adalah placeholder untuk argumen 1 atau lebih, sementara [name]* adalah pengganti untuk 0 atau lebih).

@return

Kebanyakan metode Anda akan mengembalikan nilai, jadi ini adalah tag yang mendeskripsikan nilai. Jangan lupa untuk memberitahu type nilainya, dan berikan deskripsi.

@type

Ingat tag primer @property? Anda akan menentukan type dari properties, benar? Nah, hanya @type yang Anda butuhkan. Menentukan type setelah tag; anda juga dapat menawarkan beberapa jenis dengan memisahkannya dengan bar vertikal:

@private / @protected

Bahasa pemrograman tradisional menawarkan private properti atau method: ini tidak dapat diakses dari luar contoh. Seperti konstanta, JavaScript memilikinya hanya dengan latihan saja, tetapi anda dapat menggunakan @private untuk tag ini jika anda menggunakannya. Perhatikan bahwa YUIDoc tidak menunjukkan properti pribadi dalam dokumen yang dihasilkannya (yang masuk akal), jadi ini memungkinkan Anda untuk mendokumentasikan fitur untuk kepentingan Anda sendiri dan tidak memunculkannya di dokumen.

Protected properti dan metode adalah tengah-tengah antara publik dan pribadi: hanya dapat diakses dari dalam instance dan instance subclass. Jika itu adalah hal yang Anda lakukan dalam JavaScript, iniah tag Anda: @protected.

@requires

Jika modul tergantung pada satu atau lebih modul lainnya, Anda dapat menggunakan @requires untuk menandainya:

Perhatikan bahwa @requires juga dapat mengambil daftar dependancies, dipisahkan dengan koma.

@default

Ketika mendeklarasikan @property, Anda mungkin menemukan itu berguna untuk memberi nilai @default. @default selalu dapat digunakan dengan @type.

@uses

Seperti kami katakan, JavaScript tidak benar-benar memiliki kelas, tapi itu cukup fleksibel untuk menciptakan ilusi kelas, dan bahkan sub-kelas. Apa yang bahkan lebih keren adalah bahwa itu cukup fleksibel untuk memiliki mixins atau modul: ini adalah di mana satu kelas "borrows" properti atau metode dari kelas lain. Dan itu bukan inheritance juga, karena Anda dapat mencampur di bagian lebih dari satu kelas (tentu saja, YUI memiliki kemampuan untuk melakukan hal ini, tapi begitu juga Dojo dan perpustakaan lain). Jika Anda melakukan ini, Anda akan menemukan @uses sangat berguna: hal ini memungkinkan Anda mendeklarasikan kelas tertentu adalah mencampur di bagian.

Catatan: aku hanya terdiri atas sintaks mixin itu, tapi aku cukup yakin aku pernah melihat sesuatu yang serupa di suatu tempat.

@example

Ingin menyertakan contoh bagaimana menggunakan bagian tertentu dari kode? Menggunakan tag @example, dan kemudian menulis contoh di bawah ini, indentasi satu tingkat. Anda dapat menambahkan contoh sebanyak yang Anda inginkan.

@chainable

Anda mungkin akrab dengan metode chainable dari jQuery. Kau tahu, dimana Anda dapat memanggil metode dari metode call, karena metode mengembalikan object? Tandai metode Anda seperti dengan @chainable.

@deprecated / @since / @beta

Tiga tag ini adalah semua tentang dukungan untuk kode (dan itu bisa setiap kode: module, class, method, atau sesuatu yang lain). Gunakan @deprecated untuk menandai beberapa fungsi sebagai tidak dipakai lagi (fungsionalitas yang tak berlaku lagi akan mungkin dihapus di versi masa depan dari kode). Opsional, Anda dapat menyertakan pesan yang menjelaskan apa cara termudah untuk melakukannya.

Tag @since hanya memberitahu pembaca apa versi kode yang diberikan apa yang ditambahkan dalamnya. Dan @beta menandakan kode beta: YUI menunjukkan bahwa kode @beta mungkin "mengalami mundur tidak kompatibel dengan perubahan di masa depan."

@extension / @extensionfor / extension_for

Tag @extension (dan dengan alias) adalah cukup banyak kebalikan dari @uses. Gunakan ini untuk menandai kelas mana yang bisa digabungkan dengan kelas ekstensi. Tentu saja, menyadari bahwa ini tidak berarti itu selalu dicampur dalamnya, hal itu bisa.


Komentar dan Markdown

Sebelum kita melihat contoh aktual, biarkan aku menunjukkan dua hal lagi tentang dokumentasi komentar blok.

Pertama, Anda akan sering ingin menambahkan sedikit lebih banyak informasi tentang kode Anda daripada apa yang Tag tawarkan. Mungkin Anda ingin untuk menjelaskan tujuan dari metode, atau bagaimana kelas cocok ke dalam gambar yang lebih besar. Tambahkan komentar ini di bagian atas dari blok komentar, di atas tag. YUIDoc akan memperhatikannya dan memasukkannya dalam dokumentasi.

Kedua, Anda akan senang mengetahui bahwa komentar ini, Deskripsi atau pesan setelah tag, serta dapat ditulis dalam penurunan harga, dan YUIDoc akan mengkonversi ke HTML yang benar. Anda bahkan dapat indent blok kode contoh dalam komentar Anda dan mendapatkan syntax highlighting! 


Contoh

Sekarang bahwa Anda telah belajar tag, mari kita benar-benar menulis beberapa kode dan dokumen itu. Mari kita membuat modul Store, yang memiliki dua kelas: Item dan Cart. Setiap Item contoh akan menjadi jenis barang di inventaris toko: dan memiliki nama, harga, dan kuantitas. Sebuah Cart misalnya dapat menambahkan item ke keranjang dan menghitung harga total item dalam keranjang (termasuk pajak). Itu cukup sederhana, tetapi memberikan kita cukup beragam fungsi untuk menggunakan banyak tag yang telah kita bahas. Aku telah meletakkan semua kode berikut di store.js.

Kita mulai dengan membuat modul:

Sekarang, mari kita membuat "konstanta": tax rate.

Ini adalah konstan (@final) @property @type Number. Pemberitahuan aku telah menyertakan @static: hal ini karena, untuk beberapa alasan, ketika kita menghasilkan dokumentasi untuk file ini, YUIDoc akan menampilkan ini sebagai properti kelas Item: tampaknya bahwa YUIDoc tidak mendukung memiliki properti pada modul. Saya kira saya bisa membuat kelas statis untuk menahan konstanta ini (dan konstanta lain yang mungkin datang jika kami mengembangkannya lebih lanjut), tetapi saya telah membiarkannya dengan cara ini sebagai pengingat: untuk menggunakan alat seperti YUIDoc hingga potensi maksimalnya, Anda mungkin harus mengubah cara Anda membuat kode. Anda harus memutuskan apakah itu yang ingin Anda lakukan.

Sekarang, untuk kelas Item:

Seperti yang Anda lihat, konstruktor ini memiliki tiga parameter. Kemudian, ada tiga properti dalam konstruktor yang juga kami deskripsikan. Karena kami ingin memberikan setiap Item ID unik, kita perlu menyimpan statis (tingkat-kelas) properti untuk peningkatan ID, dan properti statis lain, obyek yang melacak Item dengan ID

Bagaimana dengan kelas Cart?

Tidak ada benar-benar sesuatu yang baru di sini: Perhatikan bahwa kita sedang menyatakan bahwa default (atau awal) adalah keadaan properti item sebagai objek kosong.

Sekarang, methods. Untuk addItem, salah satu parameter opsional, jadi kita menyatakan hal itu, dan memberikan nilai default 1. Juga, perhatikan bahwa kita membuat metode @chainable.

Akhirnya, kami ingin dapat mengembalikan harga total, termasuk pajak. Perhatikan bahwa kita lakukan matematika harga dalam sen, dan kemudian mengkonversi dolar dan pembulatan ke dua angka desimal.

Jika Anda ingin menguji kode ini, berikut adalah tes sederhana:


Menghasilkan Dokumentasi

Sekarang bahwa kita sudah menulis blok kode dan komentar, saatnya untuk menghasilkan dokumentasi.

Jika Anda telah terinstal secara global melalui npm, Anda akan mampu cukup menjalankan yuidoc {path ke js}. Dalam kasus saya, itu

Sekarang, Anda akan melihat bahwa Anda memiliki direktori out dalam folder itu; Buka out/index.html, dan Anda akan melihat dokumentasi. Berikut adalah bagian dari kelas Cart dokumentasi akan terlihat seperti:

YUIDoc Documentation

Mengkonfigurasi Output

Ada beberapa opsi konfigurasi yang dapat Anda atur ketika menggunakan YUIDoc. Tentu, Anda dapat mengaturnya sebagai baris perintah, tapi aku memilih untuk menetapkan mereka dalam JSON config file. Dalam direktori proyek Anda, buatlah sebuah file bernama yuidoc.json. Pertama, ada sekelompok informasi umum proyek yang dapat Anda atur; Hal ini tidak benar-benar mempengaruhi output terlalu banyak, tapi ada baiknya untuk dokumen mereka:

Kemudian, ada sejumlah pilihan aktual yang dapat Anda atur. Berikut adalah beberapa yang menarik;

  • linkNatives: set ini menjadi "true" untuk link jenis asli seperti String atau Number ke MDN docs.
  • outdir: gunakan yang satu ini untuk mengubah nama direktori out
  • paths: gunakan ini untuk menetapkan path yang YUIDoc cari untuk file JavaScript.
  • exclude: setel ini ke daftar file yang dipisahkan koma yang Anda ingin agar YUIDoc mengabaikannya.

Selama Anda mengatur pilihan paths, Anda dapat menjalankan yuidoc - c yuidoc.json dan YUIDoc akan berjalan. Bahkan jika Anda tidak menetapkan paths dan hanya menjalankan yuidoc ., YUIDoc akan melihat config file dan menerapkannya.

Berikut ini file konfigurasi total saya untuk proyek ini:


Evaluasi

Berdasarkan Tag YUIDoc menawarkan, Anda dapat melihat bahwa itu dibuat untuk JavaScript ditulis dalam gaya tradisional OOP, juga khusus untuk YUI widget dan semacamnya (sebenarnya, aku sudah meninggalkan beberapa tag yang YUI-spesifik). Karena semua ini, Anda mungkin menemukan bahwa beberapa tag tidak hanya yang berguna untuk Anda. Kemudian, Anda harus bertanya pada diri sendiri apakah Anda bersedia untuk mengubah gaya pengkodean untuk lebih cocok dengan cara YUIDoc "pikirkanlah." Tapi bahkan jika Anda tidak akan berubah, saya pikir Anda akan menemukan bahwa kebanyakan YUIDoc Tag akan cocok saja.

Pertanyaan terbesar bagi saya adalah apakah Anda ingin memiliki inline dokumentasi dalam kode Anda.

Contoh kode yang kita tulis di atas adalah 120 baris dengan komentar, 40 baris. Jelas, itu kode super sederhana, dan hampir semua contoh dunia nyata akan lebih seimbang; Namun, membaca kode yang diselingi seperti itu bisa jadi sulit. Secara pribadi, saya pikir saya akan memberikan uji coba yang adil kepada YUIDoc: Saya akan mendokumentasikan JavaScript saya saat saya menulisnya (atau setidaknya, di sampingnya) selama beberapa minggu ke depan. Aku akan tertarik untuk melihat apakah atau bagaimana hal itu mempengaruhi saya pengkodean gaya dan alur kerja.

Anda tahu rutinitas: suka atau benci, beri tahu saya di komentar!


Untuk Lebih Lanjut

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.