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: podpowiadanie parametrów i opisywanie funkcji podczas pisania.
  2. Funkcje niestandardowe w Arkuszach Google: dokumentowanie funkcji niestandardowych, aby pojawiały się w pomocniku formuł Arkuszy.
  3. Adnotacje na poziomie skryptu: używanie specjalnych tagów do kontrolowania zachowania skryptu w całej domenie, np. autoryzacji.

Funkcje dokumentu

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

/**
 * 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 Apps Script będzie wyświetlać 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: liczba – wartość do pomnożenia.

Wspólne tagi

Tag Opis
@param {type} name description Dokumentuje parametr funkcji. Środowisko programistyczne używa wartości {type} i description do autouzupełniania.
@return {type} description Dokumentuje wartość zwracaną przez funkcję.
@example Zawiera 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 unii

Jeśli parametr lub wartość zwracana może być jednego z kilku typów, użyj znaku pionowej kreski (|), aby utworzyć typ sumy. Jest to powszechne w Apps Script w przypadku funkcji, które mogą akceptować pojedynczą wartość lub zakres wartości (reprezentowany jako tablica dwuwymiarowa).

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

W przypadku funkcji o złożonych sygnaturach, w których dozwolone parametry zależą od siebie, możesz użyć tagu @overload, aby zdefiniować każdą odrębną sygnaturę. Edytor skryptów Apps Script używa tych informacji, aby wyświetlać konkretne wskazówki w zależności od tego, której wersji funkcji używasz.

/**
 * @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 pojawiła się w podpowiedziach i pomocy dotyczącej formuł w arkuszu kalkulacyjnym.

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 jakich parametrów wymaga.

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: wymagane, aby funkcja była widoczna na liście formuł Arkuszy.
  • @param: nazwa i opis są wyświetlane w pomocniku formuł Arkuszy.
  • @return: opis podany w tagu @return nie jest wyświetlany w pomocniku formuł Arkuszy.
  • 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 jako wymagane w pomocy dotyczącej formuł.
  • Wartości domyślne: domyślne wartości parametrów (np. [name=Value]) nie są obsługiwane w interfejsie Arkuszy.
  • Formatowanie: tagi HTML i podziały wierszy w opisie w formacie zwykłego tekstu 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 widzą użytkownicy w Arkuszach Google

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

CALCULATEDISCOUNT

Oblicza rabat.

price: cena pierwotna.

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

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

Adnotacje na poziomie skryptu

Apps Script używa unikalnych tagów JSDoc do kontrolowania ustawień całego skryptu. Zazwyczaj umieszcza się je na początku pliku skryptu.

Tagi autoryzacji

Tag Opis
@OnlyCurrentDoc Informuje Apps Script, że ma 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żywana w bibliotekach do zastępowania odziedziczonej adnotacji @OnlyCurrentDoc.