Skip to content

Instantly share code, notes, and snippets.

@tanaikech
Last active Aug 12, 2022
Embed
What would you like to do?
Report: Documentation Comments including JsDoc for Functions of Google Apps Script

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

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

  • It seems that in the current stage, HTML tags cannot be used.

  • Although I searched whether Markdown can be used for the documentation comments for the functions of Google Apps Script, I couldn't find them. If you can find the official document of this, when you tell me, I'm glad.

@rjmccallumbigl
Copy link

rjmccallumbigl commented Aug 7, 2022

This is so wild to me! I didn't even know Google Apps Script supports Markdown lol thank you Tanaikech!

@tanaikech
Copy link
Author

tanaikech commented Aug 7, 2022

@rjmccallumbigl Thank you for your comment. I was surprised when I notice this, too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment