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

【问题标题】：What's the best way to document an array of arrays of arrays using JSDoc?使用 JSDoc 记录数组数组的最佳方法是什么？
【发布时间】：2021-04-02 19:33:52
【问题描述】：

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

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

【问题讨论】：

@typedef Array[Array[string|number]] whatever 是我的猜测。但是，无论如何，JSDoc 在文档化现代 JS 方面存在许多问题，尤其是在涉及解构函数参数或使用 rest spread 或 ... 这就像 webpack 和许多其他库之类的打包程序的问题一样/tools 围绕 JS 生态系统。 JS 现在发展太快了，尤其是 Chromium 很早就集成了许多第 3 阶段的提案。工具跟不上。
@connexo 是的，这是正确的。我要做的就是用一个更简单的解决方案替换 TypeScript 的使用，该解决方案只在 JS 文件中编写（未编译）代码时检查类型。感谢您的回答！
因为我不喜欢任何不能直接在浏览器中运行的技术，所以我可以支持你的方法。 medium.com/@trukrs/type-safe-javascript-with-jsdoc-7a2a63209b76
@connexo 哇！我感谢链接和内容丰富的答案！

标签： javascript jsdoc

【解决方案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

【讨论】：