Apps Komut Dosyası'nda JSDoc

Google E-Tablolar kullanıcı arayüzündeki dokümanlar ve komut dosyası düzeyindeki ek açıklamalar.

Google Apps Komut Dosyası, komut dosyalarınız için doküman oluşturmak ve otomatik tamamlama özelliğini kullanmak üzere JSDoc'u kullanır. JSDoc, yorumları kullanarak JavaScript kodunu belgelemek için kullanılan bir standarttır.

Apps Komut Dosyası'nda JSDoc şu temel amaçlara hizmet eder:

  1. Düzenleyicide otomatik tamamlama: Siz yazarken parametre ipuçları ve işlev açıklamaları sağlar.
  2. Google E-Tablolar'daki özel işlevler: Özel işlevlerinizi, E-Tablolar formül yardımcısında görünecek şekilde belgeleme.
  3. Komut dosyası düzeyinde ek açıklamalar: Yetkilendirme gibi komut dosyası genelindeki davranışları kontrol etmek için özel etiketler kullanma.

Doküman işlevleri

Bir işlevi belgelemek için JSDoc yorum bloğunu doğrudan işlev bildiriminin üzerine yerleştirin. JSDoc yorumu /** ile başlar ve */ ile biter.

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

Bir işlevi bu şekilde dokümante ettiğinizde, Apps Komut Dosyası Düzenleyicisi işlevi referans aldığınızda bir doküman ipucu gösterir. Örneğin, düzenleyicide double( yazdığınızda şunları görürsünüz:

double(input)

Bir giriş değerini 2 ile çarpar.

input: sayı - Çarpılacak değer.

Sık kullanılan etiketler

Etiket Açıklama
@param {type} name description Bir işlev parametresini belgeler. {type} ve description, geliştirme ortamı tarafından otomatik tamamlama için kullanılır.
@return {type} description İşlevin dönüş değerini belgeler.
@example İşlevin nasıl kullanılacağına dair bir örnek verir.

Aşırı yükler ve birden fazla tür

JavaScript, klasik işlev aşırı yüklemesini (aynı ada sahip birden fazla işlev tanımlama) desteklemese de farklı giriş türlerini işleyen tek bir işlev yazabilirsiniz. Bu "aşırı yüklenmiş" davranışları JSDoc'ta belgeleyebilirsiniz.

Birleşim türleri

Bir parametre veya dönüş değeri birkaç türden biri olabiliyorsa birleşim türü oluşturmak için dikey çizgi (|) kullanın. Bu durum, tek bir değeri veya değer aralığını (2 boyutlu dizi olarak gösterilir) kabul edebilen işlevler için Apps Komut Dosyası'nda yaygındır.

/**
 * 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 ile birden fazla imza

İzin verilen parametrelerin birbirine bağlı olduğu karmaşık imzalı işlevlerde, her bir farklı imzayı tanımlamak için @overload etiketini kullanabilirsiniz. Apps Komut Dosyası Düzenleyicisi, hangi işlev sürümünü çağırdığınıza bağlı olarak belirli ipuçları sağlamak için bunları kullanır.

/**
 * @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 E-Tablolar'daki özel işlevler

Google E-Tablolar için özel işlev yazdığınızda, işlevin e-tablonun otomatik tamamlama ve formül yardımcısında görünmesi için @customfunction etiketini kullanmanız gerekir.

JSDoc, kullanıcıların Google E-Tablolar'da özel işlevinizi kullanırken gördüğü yardımcı metnin kaynağıdır. JSDoc olmadan kullanıcılar yalnızca işlev adını görür. Bu da işlevin ne yaptığını veya hangi parametreleri gerektirdiğini bilmeyi zorlaştırır.

Desteklenen etiketler ve kullanıcı arayüzü sınırlamaları

Apps Komut Dosyası çoğu standart JSDoc etiketini ayrıştırsa da özel işlevler için Google E-Tablolar kullanıcı arayüzünde bazı özel davranışlar ve sınırlamalar vardır:

  • @customfunction: İşlevin E-Tablolar formül listesinde görünmesi için gereklidir.
  • @param: Ad ve açıklama, E-Tablolar formül yardımcısında gösterilir.
  • @return: @return etiketinde sağlanan açıklama, E-Tablolar'daki formül yardımcısında gösterilmez.
  • İsteğe bağlı parametreler: İsteğe bağlı parametreler için standart JSDoc söz dizimi (ör. [name] veya name=), E-Tablolar kullanıcı arayüzü tarafından tanınmaz. Tüm parametreler, formül yardımcısında zorunlu olarak görünür.
  • Varsayılan değerler: Varsayılan parametre değerleri (ör. [name=Value]), E-Tablolar kullanıcı arayüzünde desteklenmez.
  • Biçimlendirme: Açıklamanızdaki HTML etiketleri ve düz metin satır sonları desteklenmez. E-Tablolar kullanıcı arayüzü, açıklamayı tek bir metin bloğu olarak gösterir ve çoğu HTML'yi kaldırır.

Google E-Tablolar örneği

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

Kullanıcılar Google E-Tablolar'da ne görür?

Bir kullanıcı hücreye =CALCULATEDISCOUNT( yazdığında Google E-Tablolar aşağıdaki yardım kutusunu gösterir:

CALCULATEDISCOUNT

İndirim hesaplar.

price: Orijinal fiyat.

percent: İndirim yüzdesi (ör. %10 için 0,1).

Parametrelerin açıklamalarının doğrudan JSDoc @param etiketlerinizden geldiğini unutmayın.

Komut dosyası düzeyinde ek açıklamalar

Apps Komut Dosyası, komut dosyası genelindeki ayarları kontrol etmek için benzersiz JSDoc etiketleri kullanır. Bunlar genellikle bir komut dosyası en üstüne yerleştirilir.

Yetkilendirme etiketleri

Etiket Açıklama
@OnlyCurrentDoc Apps Komut Dosyası'na, bu türdeki tüm dosyalar yerine yalnızca mevcut doküman için yetkilendirme isteğinde bulunmasını söyler. Daha fazla bilgi için [Yetkilendirme kılavuzuna](/apps-script/guides/services/authorization) bakın.
@NotOnlyCurrentDoc Kitaplıklarda devralınan bir @OnlyCurrentDoc notunu geçersiz kılmak için kullanılır.