Skip to content

Express optional parameters in both JS and JSDoc TS syntax

Mark S. Miller edited this page Jul 18, 2022 · 3 revisions

(originally from https://github.com/Agoric/agoric-sdk/pull/5635#discussion_r921713558 )

See also https://github.com/Agoric/agoric-sdk/wiki/Types-documentation

We should not just rely on the type declarations to express optionality. Types are often textually distant. The optionality of a parameter is an essential part of a function's non-formal meaning. JS has its own syntax for optional parameters. We should use that.

Ideally, we'd have a lint rule that checks that optionality declared in types agrees with optionality declared in the function. In the meantime, we should enforce that consistency by review.

/**
 * @param {int} p
 */
const f = p => ...; // good

/**
 * @param {int} [p] Our preferred jsdoc/ts optionality syntax
 */
const f = (p = whatever) => ...; // good

/**
 * @param {int} [p]
 */
const f = p => ...; // bad

/**
 * @param {int} p
 */
const f = (p = whatever) => ...; // bad
Clone this wiki locally