JSDoc ใน Apps Script

เอกสารประกอบใน UI ของ Google ชีตและคำอธิบายประกอบระดับสคริปต์

Google Apps Script ใช้ JSDoc เพื่อสร้างเอกสารประกอบและ ฟีเจอร์เติมข้อความอัตโนมัติสำหรับสคริปต์ JSDoc เป็นมาตรฐานสำหรับการเขียนเอกสารประกอบโค้ด JavaScript โดยใช้ความคิดเห็น

ใน Apps Script นั้น JSDoc มีวัตถุประสงค์หลักดังนี้

1. การเติมข้อความอัตโนมัติในตัวแก้ไข: แสดงคำแนะนำพารามิเตอร์และคำอธิบายฟังก์ชัน ขณะที่คุณพิมพ์
2. ฟังก์ชันที่กำหนดเองใน Google ชีต: เขียนเอกสารประกอบฟังก์ชันที่กำหนดเองเพื่อให้ ฟังก์ชันปรากฏในตัวช่วยสูตรของชีต
3. คำอธิบายประกอบระดับสคริปต์: ใช้แท็กพิเศษเพื่อควบคุมลักษณะการทำงานทั่วทั้งสคริปต์ เช่น การให้สิทธิ์

ฟังก์ชันเอกสาร

หากต้องการเขียนเอกสารประกอบฟังก์ชัน ให้วางบล็อกความคิดเห็น JSDoc ไว้เหนือการประกาศฟังก์ชันโดยตรง ความคิดเห็น JSDoc จะเริ่มต้นด้วย /** และสิ้นสุดด้วย */

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

เมื่อเขียนเอกสารประกอบฟังก์ชันด้วยวิธีนี้ เครื่องมือแก้ไขสคริปต์ Apps Script จะแสดงเคล็ดลับเครื่องมือเอกสารประกอบเมื่อคุณอ้างอิงฟังก์ชัน เช่น เมื่อคุณพิมพ์ double( ในตัวแก้ไข คุณจะเห็นข้อมูลต่อไปนี้

double(input)

คูณค่าอินพุตด้วย 2

input: number — ค่าที่จะคูณ

แท็กทั่วไป

แท็ก	คำอธิบาย
@param {type} name description	เขียนเอกสารประกอบพารามิเตอร์ฟังก์ชัน สภาพแวดล้อมในการพัฒนาซอฟต์แวร์จะใช้ {type} และ description สำหรับ การเติมข้อความอัตโนมัติ
@return {type} description	เขียนเอกสารประกอบค่าที่แสดงผลของฟังก์ชัน
@example	แสดงตัวอย่างวิธีใช้ฟังก์ชัน

การโอเวอร์โหลดและประเภทต่างๆ

แม้ว่า JavaScript จะไม่รองรับการโอเวอร์โหลดฟังก์ชันแบบคลาสสิก (การกำหนดฟังก์ชันหลายฟังก์ชันที่มีชื่อเดียวกัน) แต่คุณสามารถเขียนฟังก์ชันเดียวที่จัดการอินพุตประเภทต่างๆ ได้ คุณสามารถเขียนเอกสารประกอบลักษณะการทำงานที่ "โอเวอร์โหลด" เหล่านี้ใน JSDoc ได้

ประเภทสหภาพ

หากพารามิเตอร์หรือค่าที่แสดงผลเป็นค่าใดค่าหนึ่งจากหลายๆ ประเภท ให้ใช้ไปป์ (|) เพื่อสร้างประเภทสหภาพ ซึ่งเป็นเรื่องปกติใน Apps Script สำหรับฟังก์ชันที่รับค่าเดียวหรือช่วงของค่า (แสดงเป็นอาร์เรย์ 2 มิติ) ได้

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

ลายเซ็นหลายรายการที่มี @overload

สำหรับฟังก์ชันที่มีลายเซ็นที่ซับซ้อนซึ่งพารามิเตอร์ที่อนุญาตขึ้นอยู่กับพารามิเตอร์อื่นๆ คุณสามารถใช้แท็ก @overload เพื่อกำหนดลายเซ็นที่แตกต่างกันแต่ละรายการได้ ตัวแก้ไข Apps Script จะใช้แท็กเหล่านี้เพื่อแสดงคำแนะนำเฉพาะตามเวอร์ชันของฟังก์ชันที่คุณเรียก

/**
 * @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
}

ฟังก์ชันที่กำหนดเองใน Google ชีต

เมื่อเขียนฟังก์ชันที่กำหนดเองสำหรับ Google ชีต คุณต้องใช้แท็ก @customfunction เพื่อให้ฟังก์ชันปรากฏในฟีเจอร์เติมข้อความอัตโนมัติและตัวช่วยสูตรของ สเปรดชีต

JSDoc เป็นแหล่งที่มาของข้อความช่วยเหลือที่ผู้ใช้เห็นเมื่อใช้ฟังก์ชันที่กำหนดเองใน Google ชีต หากไม่มี JSDoc ผู้ใช้จะเห็นเฉพาะชื่อฟังก์ชัน ซึ่งทำให้ยากต่อการทำความเข้าใจว่าฟังก์ชันทำอะไรหรือต้องใช้พารามิเตอร์ใดบ้าง

แท็กที่รองรับและข้อจำกัดของ UI

แม้ว่า Apps Script จะแยกวิเคราะห์แท็ก JSDoc มาตรฐานส่วนใหญ่ แต่ UI ของ Google ชีตสำหรับฟังก์ชันที่กำหนดเองมีลักษณะการทำงานและข้อจำกัดบางอย่างดังนี้

• @customfunction: ต้องระบุเพื่อให้ฟังก์ชันปรากฏในรายการสูตรของชีต
• @param: ชื่อและคำอธิบายจะแสดงในตัวช่วยสูตรของชีต
• @return: คำอธิบายที่ระบุในแท็ก @return จะไม่ แสดงในตัวช่วยสูตรของชีต
• พารามิเตอร์ที่ไม่บังคับ: UI ของชีตไม่รู้จักไวยากรณ์ JSDoc มาตรฐานสำหรับพารามิเตอร์ที่ไม่บังคับ (เช่น [name] หรือ name=) พารามิเตอร์ทั้งหมดจะปรากฏเป็นพารามิเตอร์ที่ต้องระบุในตัวช่วยสูตร
• ค่าเริ่มต้น: UI ของชีตไม่รองรับค่าพารามิเตอร์เริ่มต้น (เช่น [name=Value]) ไม่ รองรับ
• การจัดรูปแบบ: ระบบไม่รองรับแท็ก HTML และการขึ้นบรรทัดใหม่ของข้อความธรรมดาในคำอธิบาย UI ของชีตจะแสดงคำอธิบายเป็นข้อความบล็อกเดียวและนำ HTML ส่วนใหญ่ออก

ตัวอย่างสำหรับ Google ชีต

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

สิ่งที่ผู้ใช้เห็นใน Google ชีต

เมื่อผู้ใช้พิมพ์ =CALCULATEDISCOUNT( ในเซลล์ Google ชีตจะแสดงกล่องตัวช่วยต่อไปนี้

CALCULATEDISCOUNT

คำนวณส่วนลด

price: ราคาเดิม

percent: เปอร์เซ็นต์ส่วนลด (เช่น 0.1 สำหรับ 10%)

โปรดทราบว่าคำอธิบายสำหรับพารามิเตอร์มาจากแท็ก JSDoc @param โดยตรง

คำอธิบายประกอบระดับสคริปต์

Apps Script ใช้แท็ก JSDoc ที่ไม่ซ้ำกันเพื่อควบคุมการตั้งค่าทั่วทั้งสคริปต์ โดยปกติแล้วแท็กเหล่านี้จะวางไว้ที่ด้านบนของไฟล์สคริปต์

แท็กการให้สิทธิ์

แท็ก	คำอธิบาย
@OnlyCurrentDoc	บอกให้ Apps Script ขอการให้สิทธิ์สำหรับเอกสารปัจจุบันเท่านั้น ไม่ใช่ไฟล์ทุกไฟล์ในประเภทนั้น ดูรายละเอียดเพิ่มเติมได้ที่ [คู่มือการให้สิทธิ์](/apps-script/guides/services/authorization)สำหรับ
@NotOnlyCurrentDoc	ใช้ในไลบรารีเพื่อลบล้างคำอธิบายประกอบที่รับช่วงมา @OnlyCurrentDoc