JSDoc type parameter `{object|boolean}`: error in object properties

[regseb]

🔎 Search Terms

jsdoc, ts8032, destructuring, object

🕗 Version & Regression Information

This is the behavior in every version I tried, and I reviewed the FAQ for entries about jsdoc

⏯ Playground Link

https://www.typescriptlang.org/play/?filetype=js#code/PQKhCgAIUgxB7eA6KFqQAIAcCGAnHAW0gG94AjAKwFMBjAFwB9zEAbanAOwF9Jz9IgoZABC+FOmz4ipAM708AS04BzXsOEBtfniT8AXgF1ROfRJDBwteJ3mQAZokgBeSAAodAShcA+UlCFrW3h2JFZ4FQ98TwBucG448Ed4NwUAV2pYpMQ3Ej5TAC5IACIARzSAD2LIbligA

💻 Code

/**
 * Foo.
 *
 * @param {object|boolean} bar       Bar.
 * @param {string}         [bar.baz] Baz.
 */
const foo = (bar) => {
    console.log(bar);
};

foo(true);
foo({ baz: "qux" });

🙁 Actual behavior

Qualified name 'bar.baz' is not allowed without a leading '@param {object} bar'.

🙂 Expected behavior

No error.

Additional information about the issue

When JSDoc describes a parameter with an object or another type (eg. {object|boolean}): it's not possible to describe object properties.

[IllusionMH]

There's no baz property on boolean, so how can you expect it to work and not be an error?

As you already use TS syntax just put whole object literal type instead of object or, if you need descriptions on separate props, use @typedef and then use that new type in union

[regseb]

If I indicate that the parameter is optional, TypeScript doesn't report an error even there's no baz property on undefined.

/**
 * Foo.
 *
 * @param {object} [bar]     Bar.
 * @param {string} [bar.baz] Baz.
 */
const foo = (bar) => {
    console.log(bar);
};

foo(undefined);
foo({ baz: "qux" });

I think TypeScript should report an error only if the parameter isn't an object:

• @param {object} bar: no error.
• @param {object|boolean} bar: no error.
• @param {boolean} bar: error.

You can define that the parameter is either an object (and its properties) or a boolean with @typedef (thanks to the workaround). It would be nice if this could be done directly with @param.

My object is too big to put it literally and we can't set descriptions for the properties.

[RyanCavanaugh]

This seems like it would create more confusion than it would solve. The current behavior is entirely justifiable (it's not clear if you're trying to augment boolean or not) and it is possible to write a separate type instead if you want to do this.

[regseb]

For a boolean, I think it's clear. But I understand that it's ambiguous depending on the type. For example, for @param {object|MyAwesomeType} bar: bar.baz is the property for the object or for MyAwesomeType (which is surely an object with properties).

You can close this issue if you want.

[typescript-bot]

This issue has been marked as "Not a Defect" and has seen no recent activity. It has been automatically closed for house-keeping purposes.