Returning Class Object of Google Apps Script with JSDoc

26 Dec 2023, 13:49

GasTips

Description

On December 7, 2020, new IDE has been released. Ref This has been helping users develop various applications using Google Apps Script with the new IDE very much. When it develops scripts and applications using Google Apps Script with the new IDE, it is considered that the existence of JSDoc in the script will be helpful for both the developers and the client users, because it is reflected in the auto-completion. However, when I tried to add the built-in Class objects of Google Apps Script for returning an object using JSDoc, unfortunately, I’m worried that the detailed official documents related to JSDoc for Google Apps Script are few. Ref and Ref In this report, I would like to introduce a method for adding JSDoc for using auto-completion of the built-in Class objects to functions of Google Apps Script.

Basic method

Here, as a simple sample, it is considered JSDoc for returning Class Spreadsheet object from a function.

1. Open script editor

Please open the script editor of Google Apps Script.

2. Confirm name of Class Spreadsheet object

Please write SpreadsheetApp.getActiveSpreadsheet on the script editor. By this, the dialog of the auto-completion is opened as follows.

You can see the method name and return value at (method) SpreadsheetApp.getActiveSpreadsheet(): SpreadsheetApp.Spreadsheet in the dialog. Here, you can confirm that the name of Class Spreadsheet object is SpreadsheetApp.Spreadsheet. This can be used as the type of return value from a function as JSDoc.

3. Sample script with JSDoc

Please copy and paste the following script.

/**
 * @returns {SpreadsheetApp.Spreadsheet} sample
 */
function sample() {
  // do something.
}

function main() {
  sample();
}

In this sample script, the function sample() is called from main(). Here, when you write sample() in the function main(), the following dialog can be seen.

You can see the return value is SpreadsheetApp.Spreadsheet. And, when you add . as follows,

You can see the methods of Class Spreadsheet in the auto-completion.

By this flow, the auto-completion of Class Spreadsheet object can be returned from a function.

Other patterns

Here, I would like to introduce various samples. I guess that those samples might help in understanding the use of Class objects of Google Apps Script with JSDoc.

1. Class Sheet

/**
 * @returns {SpreadsheetApp.Sheet} sample
 */
function sample() {
  // do something
}

function main() {
  sample();
}

2. Class Range

/**
 * @returns {SpreadsheetApp.Range} sample
 */
function sample() {
  // do something
}

function main() {
  sample();
}

3. Class File

/**
 * @returns {DriveApp.File} sample
 */
function sample() {
  // do something
}

function main() {
  sample();
}

4. Class HTTPResponse

/**
 * @returns {UrlFetchApp.HTTPResponse} sample
 */
function sample() {
  // do something
}

function main() {
  sample();
}

5. Class Drive of Drive API v3

/**
 * @returns {Drive_v3.Drive.V3.Collection.FilesCollection} sample
 */
function sample() {
  // do something
}

function main() {
  sample();
}

6. Class Permissions of Drive API v3

/**
 * @returns {Drive_v3.Drive.V3.Collection.PermissionsCollection} sample
 */
function sample() {
  // do something
}

function main() {
  sample();
}

7. Class Spreadsheet of Sheets API v4

/**
 * @returns {Sheets_v4.Sheets.V4.Collection.SpreadsheetsCollection} sample
 */
function sample() {
  // do something
}

function main() {
  sample();
}

8. Class Values of Class Spreadsheet of Sheets API v4

/**
 * @returns {Sheets_v4.Sheets.V4.Collection.Spreadsheets.ValuesCollection} sample
 */
function sample() {
  // do something
}

function main() {
  sample();
}

Note

This method can be used in the library for Google Apps Script.