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 — 곱할 값입니다.

일반 태그

태그 설명
@param {type} name description 함수 매개변수를 문서화합니다. {type} 및 description은 개발 환경에서 자동 완성에 사용됩니다.
@return {type} description 함수의 반환 값을 문서화합니다.
@example 함수 사용 방법을 보여주는 예시를 제공합니다.

오버로드 및 여러 유형

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 수식 도우미에 표시되지 않습니다.
  • 선택적 매개변수: 선택적 매개변수(예: [name] 또는 name=)의 표준 JSDoc 구문은 Sheets UI에서 인식되지 않습니다. 모든 매개변수가 수식 도우미에 필수 매개변수로 표시됩니다.
  • 기본값: Sheets UI에서는 기본 매개변수 값 (예: [name=Value])이 지원되지 않습니다.
  • 서식: 설명에 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 태그를 사용하여 스크립트 전체 설정을 제어합니다. 이러한 변수는 일반적으로 스크립트 파일의 상단에 배치됩니다.

승인 태그

태그 설명
@OnlyCurrentDoc Apps Script에 해당 유형의 모든 파일이 아닌 현재 문서에 대해서만 승인을 요청하도록 지시합니다. 자세한 내용은 [승인 가이드](/apps-script/guides/services/authorization)를 참고하세요.
@NotOnlyCurrentDoc 상속된 @OnlyCurrentDoc 주석을 재정의하기 위해 라이브러리에서 사용됩니다.