Skip to content

Instantly share code, notes, and snippets.

@tanaikech
Last active August 12, 2022 06:31
Show Gist options
  • Star 3 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save tanaikech/5615cfc34e1d41659e934a7bcbaa27cf to your computer and use it in GitHub Desktop.
Save tanaikech/5615cfc34e1d41659e934a7bcbaa27cf to your computer and use it in GitHub Desktop.
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

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

@tanaikech
Copy link
Author

@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