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.

Macarthur

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. – Vyborg

@Vyborg 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. – Macarthur

To be clear, both = and [] didn't work? – Queenstown

@Macarthur Is this what you're looking for Custom Functions in Google Sheets - AutoComplete. Mogsdad has an excellent discussion on this in How to add “custom function help” to a google spreadsheet, plus a link to a much detailed blog post. – Duong

@Duong He's specifically looking for arguments to be regarded "optional". – Queenstown

@Queenstown You're quite right-I deleted the suggestion of a possible duplicate. – Duong

Yes, both = and [] don't work. I've read through that article as well, and as @Queenstown mentioned, they don't mention optional arguments. – Macarthur

Answer 1

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

Nevarez

Would you elaborate on how you came to this conclusion? – Duong

On the Google Custom Functions page they link to the JSDoc. usejsdoc.org/about-getting-started.html When you look at the spec optional should be = or []. Both doesn't work. – Nevarez

You should have included this in your answer. – Duong

I was more curious if others had found workarounds. @example isn't supported, but Apps Script lets you overload the type declaration instead. – Macarthur

@ehfeng, examples are created with {} tags for params – Rosel

Answer 2

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.

Queenstown