How to indicate param is optional using inline JSDoc?
JavascriptGoogle Closure-CompilerJsdocJavascript Problem Overview
According to the JSDoc wiki for @param you can indicate a @param is optional using
/**
@param {String} [name]
/
function getPerson(name) {
}
and you can indicate a param inline using
function getPerson(/String/ name) {
}
//
@param [name]
*/
function getPerson(/*String/name) {
}
But I would like to know if there is a way to do it all inline if possible.
Javascript Solutions
Solution 1 - Javascript
From official documentation:
Optional parameter
> An optional parameter named foo.
@param {number} [foo]
// or:
@param {number=} foo
> An optional parameter foo with default value 1.
@param {number} [foo=1]
Solution 2 - Javascript
After some digging up I found these are ok as well
/**
* @param {MyClass|undefined}
* @param {MyClass=}
* @param {String} [accessLevel="author"] The user accessLevel is optional.
* @param {String} [accessLevel] The user accessLevel is optional.
*/
Just slightly more visually appealing than function test(/**String=*/arg) {}
Solution 3 - Javascript
I found a way to do this using Google Closure Compiler type expressions. You put an equals sign after the type like so:
function test(/**String=*/arg) {}
Solution 4 - Javascript
In case you are using inline type comments on function arguments and are wondering how to mark a function argument as optional in that notation, I found that just assigning default values to the optional arguments worked. If you want the default to be undefined you have to set it explicitly as well though, otherwise the argument won't be marked as optional (even if it preceded by already optional arguments):
function demo(
/** @type {String} */ mandatory,
/** @type {Number} */ optional1 = 0,
/** @type {Number} optional2 = undefined,
)
If you hover over demo in your IDE you should see both optional1 and optional2 showing up as optional now. In VSCode that is indicated by ? after the argument name (TypeScript notation). If you remove = undefined from optional2 you will see only optional1 being optional which is of course nonsense so the default value here must be explicit like I alluded to in the above paragraph.