JSDoc di Apps Script

dokumentasi di UI Google Spreadsheet, dan anotasi tingkat skrip.

Google Apps Script menggunakan JSDoc untuk membuat dokumentasi dan melengkapi otomatis skrip Anda. JSDoc adalah standar untuk mendokumentasikan kode JavaScript menggunakan komentar.

Di Apps Script, JSDoc memiliki tujuan utama berikut:

  1. Pelengkapan otomatis di editor: Memberikan petunjuk parameter dan deskripsi fungsi saat Anda mengetik.
  2. Fungsi kustom di Google Spreadsheet: Mendokumentasikan fungsi kustom agar muncul di bantuan formula Spreadsheet.
  3. Anotasi tingkat skrip: Menggunakan tag khusus untuk mengontrol perilaku di seluruh skrip, seperti otorisasi.

Fungsi dokumen

Untuk mendokumentasikan fungsi, tempatkan blok komentar JSDoc tepat di atas deklarasi fungsi. Komentar JSDoc dimulai dengan /** dan diakhiri dengan */.

/**
 * Multiplies an input value by 2.
 *
 * @param {number} input The value to multiply.
 * @return {number} The input multiplied by 2.
 */
function double(input) {
  return input * 2;
}

Saat Anda mendokumentasikan fungsi dengan cara ini, editor Apps Script akan menampilkan tooltip dokumentasi saat Anda mereferensikan fungsi tersebut. Misalnya, saat Anda mengetik double( di editor, Anda akan melihat:

double(input)

Mengalikan nilai input dengan 2.

input: angka — Nilai yang akan dikalikan.

Tag umum

Tag Deskripsi
@param {type} name description Mendokumentasikan parameter fungsi. {type} dan description digunakan oleh lingkungan pengembangan untuk pelengkapan otomatis.
@return {type} description Mendokumentasikan nilai yang ditampilkan fungsi.
@example Memberikan contoh cara menggunakan fungsi.

Overload dan beberapa jenis

Meskipun JavaScript tidak mendukung overloading fungsi klasik (menentukan beberapa fungsi dengan nama yang sama), Anda dapat menulis satu fungsi yang menangani berbagai jenis input. Anda dapat mendokumentasikan perilaku "overload" ini di JSDoc.

Jenis gabungan

Jika parameter atau nilai yang ditampilkan dapat berupa salah satu dari beberapa jenis, gunakan garis vertikal (|) untuk membuat jenis gabungan. Hal ini umum di Apps Script untuk fungsi yang dapat menerima satu nilai atau rentang nilai (direpresentasikan sebagai array 2D).

/**
 * Multiplies an input value (or a range of values) by 2.
 *
 * @param {number|number[][]} input The value or 2D array to multiply.
 * @return {number|number[][]} The result.
 */
function double(input) {
  return Array.isArray(input) ?
      input.map(row => row.map(cell => cell * 2)) :
      input * 2;
}

Beberapa tanda tangan dengan @overload

Untuk fungsi dengan tanda tangan kompleks yang parameter yang diizinkannya bergantung satu sama lain, Anda dapat menggunakan tag @overload untuk menentukan setiap tanda tangan yang berbeda. Editor Apps Script menggunakan ini untuk memberikan petunjuk khusus berdasarkan versi fungsi yang Anda panggil.

/**
 * @overload
 * @param {string} name The name of the property to get.
 * @return {string} The property value.
 */
/**
 * @overload
 * @param {number} index The index of the item to get.
 * @return {object} The item object.
 */
function get(arg) {
  // Implementation that handles both cases
}

Fungsi kustom di Google Spreadsheet

Saat menulis fungsi kustom untuk Google Spreadsheet, Anda harus menggunakan tag @customfunction agar fungsi tersebut muncul di pelengkapan otomatis dan bantuan formula spreadsheet.

JSDoc adalah sumber untuk teks bantuan yang dilihat pengguna saat mereka menggunakan fungsi kustom Anda di Google Spreadsheet. Tanpa JSDoc, pengguna hanya akan melihat nama fungsi, sehingga sulit untuk mengetahui fungsi tersebut melakukan apa atau parameter apa yang diperlukan.

Tag yang didukung dan batasan UI

Meskipun Apps Script mem-parsing sebagian besar tag JSDoc standar, UI Google Spreadsheet untuk fungsi kustom memiliki beberapa perilaku dan batasan tertentu:

  • @customfunction: Diperlukan agar fungsi muncul dalam daftar formula Spreadsheet.
  • @param: Nama dan deskripsi ditampilkan di bantuan formula Spreadsheet.
  • @return: Deskripsi yang diberikan dalam tag @return tidak ditampilkan di bantuan formula Spreadsheet.
  • Parameter opsional: Sintaks JSDoc standar untuk parameter opsional (misalnya, [name] atau name=) tidak dikenali oleh UI Spreadsheet. Semua parameter akan muncul sebagai wajib di bantuan formula.
  • Nilai default: Nilai parameter default (misalnya, [name=Value]) tidak didukung di UI Spreadsheet.
  • Pemformatan: Tag HTML dan jeda baris teks biasa dalam deskripsi Anda tidak didukung. UI Spreadsheet menampilkan deskripsi sebagai satu blok teks dan menghapus sebagian besar HTML.

Contoh untuk Google Spreadsheet

/**
 * Calculates a discount.
 *
 * @param {number} price The original price.
 * @param {number} percent The discount percentage (e.g., 0.1 for 10%).
 * @return {number} The price after discount.
 * @customfunction
 */
function calculateDiscount(price, percent) {
  return price * (1 - percent);
}

Yang dilihat pengguna di Google Spreadsheet

Saat pengguna mengetik =CALCULATEDISCOUNT( dalam sel, Google Spreadsheet akan menampilkan kotak bantuan berikut:

CALCULATEDISCOUNT

Menghitung diskon.

price: Harga asli.

persen: Persentase diskon (misalnya, 0,1 untuk 10%).

Perhatikan bahwa deskripsi untuk parameter berasal langsung dari tag JSDoc @param Anda.

Anotasi tingkat skrip

Apps Script menggunakan tag JSDoc unik untuk mengontrol setelan di seluruh skrip. Biasanya ditempatkan di bagian atas file skrip.

Tag otorisasi

Tag Deskripsi
@OnlyCurrentDoc Memberi tahu Apps Script untuk hanya meminta otorisasi untuk dokumen saat ini, bukan semua file jenis tersebut. Lihat [Panduan otorisasi](/apps-script/guides/services/authorization) untuk detail selengkapnya.
@NotOnlyCurrentDoc Digunakan di library untuk mengganti anotasi @OnlyCurrentDoc yang diwariskan.