How to indicate param is optional using inline JSDoc?

Question

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) {
}

And I can combine them like the following, which works ok.

/**
    @param [name]
*/
function getPerson(/**String*/name) {
}

But I would like to know if there is a way to do it all inline if possible.

Solution 1

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 2

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 3

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 4

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.

View more solutions

Comments

[Peter Aron Zentai]

WebStorm /IntellIDEA supports this notation

[studgeek]

@PeterAronZentai, I'll add WebStorm/IntelliIDEA supports it as a result of me putting a feature request in for it :). They now support the majority of the Google Closure Compiler type expressions which is great.

[studgeek]

Those are valid (and documented in JSDoc help), but they are not inline - which is what I was looking for.

[DaveWalley]

Not working for me for an optional second parameter.

[Ken Bellows]

Question is about inline JSDoc notation. This is interesting information, but does not answer the question

[studgeek]

I was asking how to do it inline. The example you are providing seem to be the same as what I showed in my question.

[Jacob]

@studgeek What a stud!