In JSDoc, how to document an array accepting multiple object class like this:
var arr = [new Foo(), new Bar()];
How to write the type such that Foo and Bar are the only class that are accepted in the array?
1 Answer
If the type of the first object should always be Foo and the second always Bar, we're looking at what would be understood as a tuple object. In this case, the correct JSDoc type would be:
/** @type {[Foo, Bar]} */
const arr = [new Foo(), new Bar()];
And not Array<Foo|Bar> as one could've thought, since the latter allows for things like [new Foo(), new Foo()], which is probably undesired.
5 Comments
Captain_Obvious
in
jsdoc 3.6.3 (and I assume all earlier versions), this syntax is illegal and throws an error
Yves M.
Is there any official documentation about this JSDoc notation? See github.com/gajus/eslint-plugin-jsdoc/issues/…
dannymo
I am afraid that
[Foo, Bar] is used for tuples. I.e. a tuple with exactly two elements where the first one is Foo and the second Bar. A general array that can have multiple Foos and Bars will be (Foo|Bar)[] as @austin_ce suggested.
Lucio Paiva
You are correct, @dannymo. If you read my answer carefully, you'll see that it presupposes a tuple with predetermined types for each position. For an array where types can be at any position, austin_ce's suggestion is correct indeed.
abulka
Its 2022 and this syntax is still illegal. Whilst vscode can handle this syntax, the
jsdoc CLI cannot.
/** @type {[Foo|Bar]} */{Array.<Foo|Bar>}{(Foo|Bar)[]}[Foo|Bar]would mean a one element tuple where the first/only element isFooorBar.