JSDoc w Apps Script

dokumentacja w interfejsie Arkuszy Google i adnotacje na poziomie skryptu.

Google Apps Script używa JSDoc do generowania dokumentacji i autouzupełniania skryptów. JSDoc to standard dokumentowania kodu JavaScript za pomocą komentarzy.

W Apps Script JSDoc służy do tych głównych celów:

  1. Autouzupełnianie w edytorze: podczas pisania podpowiada parametry i wyświetla opisy funkcji.
  2. Funkcje niestandardowe w Arkuszach Google: dokumentuje funkcje niestandardowe, aby były widoczne w pomocy dotyczącej formuł w Arkuszach.
  3. Adnotacje na poziomie skryptu: używa specjalnych tagów do kontrolowania zachowania w całym skrypcie, np. autoryzacji.

Funkcje dokumentu

Aby udokumentować funkcję, umieść blok komentarza JSDoc bezpośrednio nad deklaracją funkcji. Komentarz JSDoc zaczyna się od /** i kończy się */.

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

Gdy udokumentujesz funkcję w ten sposób, edytor skryptów Apps Script wyświetli etykietkę z dokumentacją, gdy odwołasz się do tej funkcji. Na przykład, gdy w edytorze wpiszesz double(, zobaczysz:

double(input)

Mnoży wartość wejściową przez 2.

input: number – wartość do pomnożenia.

Typowe tagi

Tag Opis
@param {type} name description Dokumentuje parametr funkcji. Środowisko programistyczne używa {type} i description do autouzupełniania.
@return {type} description Dokumentuje wartość zwracaną przez funkcję.
@example Podaje przykład użycia funkcji.

Przeciążenia i wiele typów

JavaScript nie obsługuje klasycznego przeciążania funkcji (definiowania wielu funkcji o tej samej nazwie), ale możesz napisać jedną funkcję, która obsługuje różne typy danych wejściowych. Te „przeciążone” zachowania możesz udokumentować w JSDoc.

Typy sum

Jeśli parametr lub wartość zwracana może być jednym z kilku typów, użyj pionowej kreski (|), aby utworzyć typ sum. Jest to powszechne w Apps Script w przypadku funkcji, które mogą przyjmować pojedynczą wartość lub zakres wartości (reprezentowany jako tablica 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;
}

Wiele podpisów z tagiem @overload

W przypadku funkcji ze złożonymi podpisami, w których dozwolone parametry zależą od siebie, możesz użyć tagu @overload, aby zdefiniować każdy odrębny podpis. Edytor skryptów Apps Script używa tych informacji do podawania konkretnych wskazówek na podstawie wersji funkcji, którą wywołujesz.

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

Funkcje niestandardowe w Arkuszach Google

Gdy piszesz funkcję niestandardową dla Arkuszy Google, musisz użyć tagu @customfunction, aby funkcja była widoczna w autouzupełnianiu i pomocy dotyczącej formuł w arkuszu.

JSDoc jest źródłem tekstu pomocy, który użytkownicy widzą, gdy używają Twojej funkcji niestandardowej w Arkuszach Google. Bez JSDoc użytkownicy widzieliby tylko nazwę funkcji, co utrudniałoby określenie, co robi funkcja i jakie parametry są wymagane.

Obsługiwane tagi i ograniczenia interfejsu

Apps Script analizuje większość standardowych tagów JSDoc, ale interfejs Arkuszy Google dla funkcji niestandardowych ma pewne specyficzne zachowania i ograniczenia:

  • @customfunction: wymagany, aby funkcja była widoczna na liście formuł w Arkuszach.
  • @param: nazwa i opis są wyświetlane w pomocy dotyczącej formuł w Arkuszach.
  • @return: opis podany w tagu @return nie jest wyświetlany w pomocy dotyczącej formuł w Arkuszach.
  • Parametry opcjonalne: standardowa składnia JSDoc dla parametrów opcjonalnych (np. [name] lub name=) nie jest rozpoznawana przez interfejs Arkuszy. Wszystkie parametry będą wyświetlane w pomocy dotyczącej formuł jako wymagane.
  • Wartości domyślne: wartości domyślne parametrów (np. [name=Value]) nie są obsługiwane w interfejsie Arkuszy.
  • Formatowanie: tagi HTML i podziały wierszy w zwykłym tekście w opisie nie są obsługiwane. Interfejs Arkuszy wyświetla opis jako pojedynczy blok tekstu i usuwa większość kodu HTML.

Przykład dla Arkuszy 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);
}

Co użytkownicy widzą w Arkuszach Google

Gdy użytkownik wpisze w komórce =CALCULATEDISCOUNT(, Arkusze Google wyświetlą to pole pomocy:

CALCULATEDISCOUNT

Oblicza rabat.

price: cena pierwotna.

percent: procent rabatu (np. 0,1 dla 10%).

Zwróć uwagę, że opisy parametrów pochodzą bezpośrednio z tagów @param JSDoc.

Adnotacje na poziomie skryptu

Apps Script używa unikalnych tagów JSDoc do kontrolowania ustawień w całym skrypcie. Zazwyczaj umieszcza się je u góry pliku skryptu.

Tagi autoryzacji

Tag Opis
@OnlyCurrentDoc Informuje Apps Script, aby prosił o autoryzację tylko w przypadku bieżącego dokumentu, a nie wszystkich plików tego typu. Więcej informacji znajdziesz w [przewodniku po autoryzacji](/apps-script/guides/services/authorization).
@NotOnlyCurrentDoc Używany w bibliotekach do zastępowania odziedziczonej @OnlyCurrentDoc adnotacji.