使用 JSDoc 记录 arrays 的 arrays 数组的最佳方法是什么？

Question

I have the following data structure. The element types of the root array are fixed. What is the best way to document such a structure using JSDoc?

[
    [
        ['aqua-160', 160, 'PreCleaning'],
        ['aqua-260', 260, 'PreCleaning']
    ],
    [
        ['aqua-360', 360, 'PostCleaning']
    ]
];

Answer 1

I would use a @typedef for this:

/** @typedef {[string, number, string]} MyTuple */

Which you can apply as follow:

/** @type {Array<Array<MyTuple>>} */
const x = [ [ ['aqua-160', 160, 'PreCleaning']
            , ['aqua-260', 260, 'PreCleaning']]
          , [ ['aqua-360', 360, 'PostCleaning']]];

When you mouse over the x variable in VS Code here's what you can see:

With VS Code you can also do some type checking with a // @ts-check "directive" at the top of the file:

// @ts-check

/**
 * @typedef {[string, number, string]} MyTuple
 */

/** @param {Array<Array<MyTuple>>} z */
function y(z) {
  return 42;
}

y('4');

VS Code is able to see that the z parameter is wrong:

See also

• https://github.com/jsdoc/jsdoc/issues/1703