Search code examples
google-apps-scriptgoogle-sheetsjsdoccustom-function

What amount of JsDoc is supported in Google Sheets custom functions?

Google implies that JsDoc is supported:

Custom functions will appear in this list if their script includes a JsDoc @customfunction tag, as in the DOUBLE() example below.

https://developers.google.com/apps-script/guides/sheets/functions

But it doesn't seem that JsDoc is supported in full, and I can't find the documentation that shows what is supported and not.

I'm particularly looking for a way to document that a parameter for a custom function is optional. Like this, for value2:

enter image description here

Image courtesy of: https://yagisanatode.com/2018/08/24/google-apps-script-how-to-make-a-custom-function-to-use-in-google-sheets/

Using JsDoc, you should be able to do the following, based on this source: https://jsdoc.app/tags-param.html#optional-parameters-and-default-values

/**
 * @param {number} [value2] - Additional numbers or ranges to add to value1.
 */

And, with a default value:

/**
 * @param {number} [value2=100] - Additional numbers or ranges to add to value1.
 */

But I tested this in Google sheets, and none of this works. Not even the suggested Google Closure Compiler syntax (in case that should work):

/**
 * @param {number=} value2 - Additional numbers or ranges to add to value1.
 */

Currently I have resorted to the less elegant:

/**
 * @param {number} value2 - [OPTIONAL] Additional numbers or ranges to add to value1.
 */

So, where can I find the documentation over what part of JsDoc is supported in Google Sheets?

Bonus points if you can show a way to document the optional parameter using JsDoc that achieves the desired result from the screenshot (which is better than my current inelegant solution).

Solution

  • JsDoc optional arguments feature doesn't seem to be supported for Sheets custom functions, but no official documentation can be found for this.

    I'd suggest you to file a Feature Request in this component to ask for this functionality, or at least to document in more detail what functionality is supported.

    Update:

    A Feature Request regarding this was submitted in Issue Tracker by OP:

    Anyone who want to keep track of this can click the star on the top left on the referenced page.