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 ได้

ประเภทสหภาพ

หากพารามิเตอร์หรือค่าที่ส่งคืนเป็นได้หลายประเภท ให้ใช้ไปป์ (|) เพื่อสร้างประเภท Union ซึ่งเป็นเรื่องปกติใน 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=) พารามิเตอร์ทั้งหมด จะปรากฏเป็นพารามิเตอร์ที่ต้องระบุในตัวช่วยสูตร
• ค่าเริ่มต้น: ระบบไม่รองรับค่าพารามิเตอร์เริ่มต้น (เช่น [name=Value]) ใน UI ของชีต
• การจัดรูปแบบ: ระบบไม่รองรับแท็ก 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คำอธิบายประกอบที่รับช่วงมา