-
Notifications
You must be signed in to change notification settings - Fork 208
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