Apps Script의 JSDoc

Google Sheets UI의 문서 및 스크립트 수준 주석

Google Apps Script는 JSDoc을 사용하여 스크립트의 문서 및 자동 완성을 생성합니다. JSDoc은 주석을 사용하여 JavaScript 코드를 문서화하는 표준입니다.

Apps Script에서 JSDoc은 다음과 같은 주요 용도로 사용됩니다.

1. 편집기의 자동 완성: 입력할 때 매개변수 힌트와 함수 설명을 제공합니다.
2. Google Sheets의 맞춤 함수: Sheets 수식 도우미에 표시되도록 맞춤 함수를 문서화합니다.
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 — 곱할 값입니다.

일반 태그

오버로드 및 여러 유형

JavaScript는 클래식 함수 오버로드 (이름이 같은 여러 함수 정의)를 지원하지 않지만 여러 유형의 입력을 처리하는 단일 함수를 작성할 수 있습니다. JSDoc에서 이러한 '오버로드된' 동작을 문서화할 수 있습니다.

유니온 유형

매개변수 또는 반환 값이 여러 유형 중 하나일 수 있는 경우 파이프 (|)를 사용하여 유니온 유형을 만듭니다. 이는 단일 값 또는 값 범위 (2D 배열로 표시됨)를 허용할 수 있는 함수의 Apps Script에서 일반적입니다.

/**
 * 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 Sheets의 맞춤 함수

Google Sheets의 맞춤 함수를 작성할 때는 스프레드시트의 자동 완성 및 수식 도우미에 표시되도록 @customfunction 태그를 사용해야 합니다.

JSDoc은 사용자가 Google Sheets에서 맞춤 함수를 사용할 때 표시되는 도우미 텍스트의 소스입니다. JSDoc이 없으면 사용자에게 함수 이름만 표시되므로 함수가 수행하는 작업이나 필요한 매개변수를 알기 어렵습니다.

지원되는 태그 및 UI 제한사항

Apps Script는 대부분의 표준 JSDoc 태그를 파싱하지만 맞춤 함수의 Google Sheets UI에는 몇 가지 특정 동작과 제한사항이 있습니다.

• @customfunction: 함수가 Sheets 수식 목록에 표시되려면 필요합니다.
• @param: 이름과 설명이 Sheets 수식 도우미에 표시됩니다.
• @return: @return 태그에 제공된 설명은 Sheets 수식 도우미에 표시되지 않습니다.
• 선택적 매개변수: 선택적 매개변수의 표준 JSDoc 문법 (예: [name] 또는 name=)은 Sheets UI에서 인식되지 않습니다. 모든 매개변수가 수식 도우미에 필수 항목으로 표시됩니다.
• 기본값: 기본 매개변수 값 (예: [name=Value])은 Sheets UI에서 지원되지 않습니다.
• 서식: 설명의 HTML 태그와 일반 텍스트 줄바꿈은 지원되지 않습니다. Sheets UI는 설명을 단일 텍스트 블록으로 표시하고 대부분의 HTML을 삭제합니다.

Google Sheets의 예

/**
 * 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 Sheets에 표시되는 내용

사용자가 셀에 =CALCULATEDISCOUNT(를 입력하면 Google Sheets에 다음 도우미 상자가 표시됩니다.

CALCULATEDISCOUNT

할인을 계산합니다.

price: 원래 가격입니다.

percent: 할인율입니다 (예: 10%의 경우 0.1).

매개변수 설명은 JSDoc @param 태그에서 직접 가져옵니다.

스크립트 수준 주석

Apps Script는 고유한 JSDoc 태그를 사용하여 스크립트 전체 설정을 제어합니다. 일반적으로 스크립트 파일의 상단에 배치됩니다.

승인 태그