Repository navigation
Intellisense for object properties defined in multi-line JSDoc comments #11597
Description
Activity
A workaround is to write:
/** * @param {{strProp: string, numProp: number}} obj - An object parameter with string and number properties */
but that doesn't allow for documenting the specific subkeys.
Reacted by Alexey, Igor Afanasov, Mahmoud-64 and Marcin Ciarka@Kovensky Yeah, that does work, but the individual property documentation is the main reason I prefer the multi-line documenting.
Reacted by Ryan SullivanSorry, didn't mean to close/reopen this...
Would a solution to this also support destructured parameters as well?
Example: jsdoc/jsdoc#987 (comment)I haven't really used that pattern, but I would think it would. That seems to be an extension of the same underlying issue of being unable to document properties of object parameters.
How about creating a zouying (@typedef)
this works fine for me./** * @typedef {Object} GetUsersParams * @property {number} page_size - Number of results to show in a page, optional? * @property {number} page_number - Page number, optional? * @property {Object} match_params - match query, optional? */ /** * @description getUsers function can be used to fetch users * @param {GetUsersParams} params - Provide appropriate props * @param {function} cb */ function getUsers(params, cb) { // do something }I tried this, but it doesn't work
* @param {...GetUsersParams} paramsReacted by Sean G. Wright and E. Lofgren (TiER1)That's actually what I've been doing as a workaround, but it doesn't allow for documenting optional/default values.
You also don't get the text descriptions in intellisense. I wouldn't say that's necessary, but it'd be nice.
Has there been any update on this? The
@typedefworkaround is not bad, but without the support of optional parameters (which seem to be supported for jsdocs), I'm getting a lot of false positives with jscheck turned on.but without the support of optional parameters (which seem to be supported for jsdocs)
can you elaborate on this?
3 remaining items
I have a similar problem with stateless functional components in react, they are written with object destructuring and the trick with
@typedefdoesn't works because the parameter doesnt have a proper nameI have tried with
props,param0,args0but no luck 😞/** * @typedef Props * @property {string} one - first * @property {number} two - second * * @param {Props} props */ // doesn't work function Component({one, two}) { // stuff... } // works function Component(props) { const {one, two} = props // stuff... }
thanks for any advice 😄
Reacted by Oliver Joseph Ash, Adam Weber, Elvin Peng, Victor Villas, Daniel Rynaski and Martin BoriesSimone Picciani (@zanza00) you can you specify the type inline:
function Component(/** @type {Props} */ { one, two }) { // stuff ... }
Reacted by Oliver Joseph Ash, Simone Picciani, Yang Jun, Nicolas PENNEC, Victor Villas, Max Milton, Eugene Kulabuhov, Lev Izraelit, X.L, Tri-Bac Nguyen and 1 moreReacted by Max Milton and Michael LeaneyI can confirm that indeed it works, thanks
Fix is up at #17352
Nathan Shively-Sanders (@sandersn) It's still not possible to have a destructured parameter with
@paramannotations.Example:
/** * @typedef BarBaz * @property {string} bar * @property {string} baz */ /** * @param {BarBaz} options Your configuration object */ function foo({bar, baz}) { }
Error
error TS8024: JSDoc '@param' tag has name 'options', but there is no parameter with that name. 338 * @param {BarBaz} options Your configuration object ~~~~~~~I can change my code to:
function foo(/** @type {BarBaz} */{bar, baz}) { }
but then where should I put the parameter description text?
Also see webpack/webpack#6988
Mohsen Azimi (@mohsen1) that’s a slightly different issue than this one, and is tracked at #19645.
The PR with the fix is at #18832. I’ll take another look at it; last I remember we needed to check whether performance was OK with the additional upfront processing and storage it required.
Mohsen Azimi (@mohsen1) destructured parameters now look up jsdoc
@paramtags positionally. It should be available tomorrow intypescript@next.Reacted by Mohsen Azimi, Bazyli Brzóska (Zendesk), Sergio Morchón Poveda, stephen and Alexandre GaudencioWhat do you mean by
positionally?Are we heading towards something like
/** * @param {number} $0.id An id */ function foo({ id }) {}
?
Alexandre Gaudencio (@Shahor) no the syntax you would use is either
/** * @param {Object} arg * @param {number} arg.id An id */ function foo({ id }) {}
OR
/** * @param {{ id: number }} arg */ function foo({ id }) {}
Reacted by Vitor L Cavalcanti and ExE BossNathan Shively-Sanders (@sandersn), the two syntaxes you've suggested above doesn't seem to work. See here.
Steve Colbow (@steph643) VS code 1.23 is running Typescript 2.8, which doesn't have the fix.
can confirm the issue, example code:
/** * @param {*} options the args object * @param {number} object.alpha first number * @param {number} object.bravo second number * @param {Function} callback the callback function * @returns {number} */ function addNumbersFromObject({ alpha = 1, bravo = 2 } = {}, callback = null) { if (!callback) return alpha + bravo; return callback(alpha + bravo); } console.log(addNumbersFromObject({ alpha: 2 }));
that results in the text not being displayed:
The workaround is to use the
@typedeflike so:/** * @typedef {Object} Opts * @property {string} alpha Alpha helping test * @property {string=} bravo Description about bravo * * @param {Opts} opts the options object * @param {Function} callback the callback function * @returns {number} */ function addNumbersFromObject({ alpha = 1, bravo = 2 } = {}, callback = null) { if (!callback) return alpha + bravo; return callback(alpha + bravo); } console.log(addNumbersFromObject({ bravo: 2 }));
Now intellisense detects the parameters as well as shows if its an optional parameter and adds description to it:
Reacted by Amadeo Gallardo, Ian Izaguirre and hinstShagon94 it should be:
/** * @param {Object} options the args object * @param {number} options.alpha first number * @param {number} options.bravo second number * @param {Function} callback the callback function * @returns {number} */ function addNumbersFromObject({ alpha = 1, bravo = 2 } = {}, callback = null) { if (!callback) return alpha + bravo; return callback(alpha + bravo); } console.log(addNumbersFromObject({ alpha: 2 }));
Reacted by Michael CoxReacted by Sophia
Currently it doesn't look like the TypeScript parser recognizes properties for an object parameter if they are defined with separate
@paramdeclarations. Would it be possible to add support for this?Thanks!