JSDoc for showing optional arguments in Google Sheets autocomplete dropdown

Question

I'd like to document (in the Google Sheet autocomplete) a custom function with optional arguments, similar to the WEEKDAY function (autocomplete below).

The JSDoc spec on optional arguments does not work. Google does not seem to document this anywhere. How can I create a function with the same visual treatment (both in the argument description and the Example) that Google has?

/**
 * Summary of function
 * @param {"example"} arg Argument description
 * @param {"optional"} opt_arg This argument is optional
 * @return {String} Return value description
 * @customfunction
 */
function JSDOC(arg, opt_arg) {
  return
}

Generates this autocomplete:

This is not a duplicate. I'm specifically asking about optional arguments, as you can see, I've successfully gotten the autocomplete's other features working.

I don't think JSDoc works the way you think it does. It's not an add on to javascript, its an interpreter of your javascript code and generates a document. — TheWizEd, Jan 27 '19 at 00:07
@TheWizEd You misunderstand my question. I'm aware that JSDoc is not a "addon" to javascript. I named the function JSDOC just randomly. I'm looking to understand the syntax that Google Apps Script supports for documenting functions, in particular their optional arguments. — ehfeng, Jan 27 '19 at 02:01
@ehfeng Is this what you're looking for [Custom Functions in Google Sheets - AutoComplete](https://developers.google.com/apps-script/guides/sheets/functions#autocomplete). Mogsdad has an excellent discussion on this in [How to add “custom function help” to a google spreadsheet](https://stackoverflow.com/a/31326326/1330560), plus a link to a much detailed blog post. — Tedinoz, Jan 27 '19 at 10:58
@Tedinoz He's specifically looking for arguments to be regarded "optional". — TheMaster, Jan 27 '19 at 13:41
@TheMaster You're quite right-I deleted the suggestion of a possible duplicate. — Tedinoz, Jan 28 '19 at 00:54
Yes, both `=` and `[]` don't work. I've read through that article as well, and as @TheMaster mentioned, they don't mention optional arguments. — ehfeng, Jan 28 '19 at 03:25

score 4 · Accepted Answer · answered Jan 27 '19 at 08:03

4

Google Apps Script doesn't support optional params in their JSDoc at this moment.

answered Jan 27 '19 at 08:03

Niek Waarbroek

162
2

2

Would you elaborate on how you came to this conclusion? – Tedinoz Jan 27 '19 at 23:11
1

On the Google Custom Functions page they link to the JSDoc. http://usejsdoc.org/about-getting-started.html When you look at the spec optional should be = or []. Both doesn't work. – Niek Waarbroek Jan 28 '19 at 05:47
2

You should have included this in your answer. – Tedinoz Jan 28 '19 at 06:04
1

I was more curious if others had found workarounds. @example isn't supported, but Apps Script lets you overload the type declaration instead. – ehfeng Jan 28 '19 at 09:44
@ehfeng, examples are created with {} tags for params – Adriano_Pinaffo May 10 '20 at 03:11

score 1 · Answer 2 · answered Apr 16 '23 at 12:49

JsDoc isn't fully supported. Specifically optional parameters isn't supported. A related tracker link is here:

https://issuetracker.google.com/issues/156230902

Anyone interested in this issue may add a +1(on the top bar, not as a comment) to this issue. They may also add a new specific feature request for the same.

JSDoc for showing optional arguments in Google Sheets autocomplete dropdown

2 Answers2

Linked

Related