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

Question

我有以下数据结构。根数组的元素类型是固定的。使用 JSDoc 记录这种结构的最佳方式是什么？

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

Answer 1

我会为此使用 @typedef：

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

您可以按以下方式申请：

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

当您将鼠标悬停在 VS Code 中的 x 变量上时，您会看到以下内容：

使用 VS Code，您还可以在文件顶部使用 // @ts-check“指令”执行一些 type checking：

// @ts-check

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

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

y('4');

VS Code 能够看到 z 参数是错误的：

另见

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

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

What's the best way to document an array of arrays of arrays using JSDoc?

javascript

jsdoc