Report: Documentation Comments including JsDoc for Functions of Google Apps Script

20 Jul 2022, 10:24

report / GasTips

This is a report for the documentation comments for the functions of Google Apps Script.

When the documentation comments for functions of Google Apps Script are considered, you will think JsDoc. At Google Apps Script, a part of JsDoc can be used. But, in this report, I would like to introduce the documentation comments including JsDoc.

Sample situations

Sample 1

For example, when the following sample function is written,

/**
 * Sample description.
 * @param {String} text Sample text.
 * @return {String} Ouput text.
 */
function myFunction(text) {}

Document of myFunction can be seen as follows.

This is a simple and typical document. In this situation, when the readability of a document is high, it is considered that it will be very useful for a lot of users. So, I tested the next sample situation.

Sample 2

In this sample, Markdown is used for writing the documentation comments. The sample script is as follows.

/**
 * ## Sample text
 * sample *sample* **sample**
 *
 * ## Sample hyperlink
 * [Sample link](https://tanaikech.github.io/)
 *
 * ## Sample image
 * ![sample image](https://stackoverflow.design/assets/img/logos/se/se-icon.png)
 *
 * ## Sample script
 * ```javascript
 * const text = "sample";
 * const res = myFunction(text);
 * ```
 *
 * ## Sample json data
 * ```json
 * {
 *   "key1": "value1",
 *   "key2": "value3",
 * }
 * ```
 * ## Sample list
 *
 * - Sample option 1
 * - Sample option 2
 * - Sample option 3
 *
 * ## Sample table
 *
 * | Header1 | Header2 | Header3 |
 * | :----:  | ------: | :------ |
 * | v1      | v2      | v3      |
 * | V4      | v5      | v6      |
 *
 * @param {String} text Sample text.
 * @return {String} Ouput text.
 */
function myFunction(text) {}

When the document of this function is seen, you can see the following situation.

You can see the document written by Markdown. Also, you can see the hyperlink, image, script, list, and table. JsDoc is also included.

Sample 3

When the above sample script is used as a Google Apps Script library, the sample script is as follows.

function myFunction() {
  sample.myFunction();
}

When the document of this function is seen, you can see the following situation.

You can see the same document using a library.

I believe that the functions and libraries of Google Apps Script will be more useful by writing the documentation comments with Markdown.

Note